diff --git a/package.json b/package.json index 8f905fb..5a553eb 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,11 @@ "import": "./dist/clients.js", "default": "./dist/clients.js" }, + "./agent-server-api": { + "types": "./dist/generated/agent-server-api.d.ts", + "import": "./dist/generated/agent-server-api.js", + "default": "./dist/generated/agent-server-api.js" + }, "./client/http-client": { "types": "./dist/client/http-client.d.ts", "import": "./dist/client/http-client.js", @@ -40,6 +45,7 @@ }, "scripts": { "build": "tsc && node ./scripts/rewrite-relative-imports.mjs", + "generate:openapi-types": "npx --yes openapi-typescript@7.13.0 swagger-doc.json --export-type --default-non-nullable false --root-types --root-types-no-schema-prefix -o src/generated/agent-server-api.ts", "lint": "eslint src/**/*.ts", "lint:fix": "eslint src/**/*.ts --fix", "format": "prettier --write \"src/**/*.ts\" \"examples/**/*.ts\" \"scripts/**/*.mjs\"", diff --git a/src/__tests__/openapi-types.test.ts b/src/__tests__/openapi-types.test.ts new file mode 100644 index 0000000..76036b8 --- /dev/null +++ b/src/__tests__/openapi-types.test.ts @@ -0,0 +1,71 @@ +import { ConversationClient } from '../clients'; +import type { CreateConversationPayload } from '../clients'; +import type { + AgentServerConversationInfo, + SettingsResponse, + SettingsUpdateRequest, + StartConversationRequest, +} from '../index'; +import type { StartConversationRequest as SubpathStartConversationRequest } from '../generated/agent-server-api'; + +const originalFetch = global.fetch; + +describe('generated Agent Server OpenAPI types', () => { + afterEach(() => { + global.fetch = originalFetch; + jest.restoreAllMocks(); + }); + + it('types ConversationClient.createConversation with StartConversationRequest', async () => { + const payload: StartConversationRequest = { + workspace: { kind: 'LocalWorkspace', working_dir: '/workspace/project' }, + agent_settings: { + agent_kind: 'openhands', + llm: { model: 'anthropic/claude-sonnet-4-5-20250929' }, + }, + max_iterations: 500, + stuck_detection: true, + }; + const clientPayload: CreateConversationPayload = payload; + const subpathPayload: SubpathStartConversationRequest = payload; + + const responseBody: Pick = { + id: '11111111-1111-1111-1111-111111111111', + }; + + global.fetch = jest.fn().mockResolvedValue( + new Response(JSON.stringify(responseBody), { + status: 200, + headers: { 'content-type': 'application/json' }, + }) + ) as typeof fetch; + + const client = new ConversationClient({ host: 'http://example.com' }); + const conversation = await client.createConversation(clientPayload); + + expect(subpathPayload.agent_settings).toEqual(payload.agent_settings); + expect(conversation.id).toBe('11111111-1111-1111-1111-111111111111'); + expect(global.fetch).toHaveBeenCalledWith( + 'http://example.com/api/conversations', + expect.objectContaining({ + method: 'POST', + body: JSON.stringify(payload), + }) + ); + }); + + it('exports generated settings request and response shapes', () => { + const update: SettingsUpdateRequest = { + agent_settings_diff: { llm: { model: 'openai/gpt-4o' } }, + conversation_settings_diff: { max_iterations: 200 }, + }; + const response: SettingsResponse = { + agent_settings: { llm: { model: 'openai/gpt-4o' } }, + conversation_settings: { max_iterations: 200 }, + llm_api_key_is_set: false, + }; + + expect(update.agent_settings_diff?.llm).toEqual({ model: 'openai/gpt-4o' }); + expect(response.llm_api_key_is_set).toBe(false); + }); +}); diff --git a/src/client/conversation-client.ts b/src/client/conversation-client.ts index 98ebfcb..baa1d8f 100644 --- a/src/client/conversation-client.ts +++ b/src/client/conversation-client.ts @@ -8,6 +8,10 @@ import type { ConversationSearchResponse, UpdateConversationRequest, } from '../models/conversation'; +import type { + ConversationInfo as AgentServerConversationInfo, + StartConversationRequest, +} from '../generated/agent-server-api'; export interface ConversationClientOptions { host: string; @@ -15,7 +19,7 @@ export interface ConversationClientOptions { timeout?: number; } -export type CreateConversationPayload = Record; +export type CreateConversationPayload = StartConversationRequest; export interface SendConversationEventOptions { run?: boolean; @@ -36,7 +40,7 @@ export class ConversationClient { }); } - async createConversation( + async createConversation( payload: CreateConversationPayload ): Promise { const response = await this.client.post('/api/conversations', payload); diff --git a/src/clients.ts b/src/clients.ts index 88f24ea..8ca1400 100644 --- a/src/clients.ts +++ b/src/clients.ts @@ -14,6 +14,20 @@ export { ApiKeysClient } from './client/api-keys-client'; export { SessionClient } from './client/session-client'; export { SharedClient } from './client/shared-client'; +export type { + paths as AgentServerPaths, + components as AgentServerComponents, + operations as AgentServerOperations, + StartConversationRequest, + StartAcpConversationRequest as StartACPConversationRequest, + ConversationInfo as AgentServerConversationInfo, + ConversationPage, + SettingsResponse, + SettingsUpdateRequest, + LocalWorkspaceInput, + AgentBaseInput, +} from './generated/agent-server-api'; + export type { ServerClientOptions } from './client/server-client'; export type { BashClientOptions } from './client/bash-client'; export type { diff --git a/src/generated/agent-server-api.ts b/src/generated/agent-server-api.ts new file mode 100644 index 0000000..3a8f5fa --- /dev/null +++ b/src/generated/agent-server-api.ts @@ -0,0 +1,13493 @@ +/** + * This file was auto-generated by openapi-typescript. + * Do not make direct changes to the file. + */ + +export type paths = { + '/alive': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Alive + * @description Basic liveness check - returns OK if the server process is running. + */ + get: operations['alive_alive_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/health': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Health + * @description Basic health check - returns OK if the server process is running. + */ + get: operations['health_health_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/ready': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Ready + * @description Readiness check - returns OK only if the server has completed initialization. + * + * This endpoint should be used by Kubernetes readiness probes to determine + * when the pod is ready to receive traffic. Returns 503 during initialization. + */ + get: operations['ready_ready_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/server_info': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get Server Info */ + get: operations['get_server_info_server_info_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/events/search': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Search Conversation Events + * @description Search / List local events + */ + get: operations['search_conversation_events_api_conversations__conversation_id__events_search_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/events/count': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Count Conversation Events + * @description Count local events matching the given filters + */ + get: operations['count_conversation_events_api_conversations__conversation_id__events_count_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/events/{event_id}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Conversation Event + * @description Get a local event given an id + */ + get: operations['get_conversation_event_api_conversations__conversation_id__events__event_id__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/events': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Batch Get Conversation Events + * @description Get a batch of local events given their ids, returning null for any + * missing item. + */ + get: operations['batch_get_conversation_events_api_conversations__conversation_id__events_get']; + put?: never; + /** + * Send Message + * @description Send a message to a conversation + */ + post: operations['send_message_api_conversations__conversation_id__events_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/events/respond_to_confirmation': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Respond To Confirmation + * @description Accept or reject a pending action in confirmation mode. + */ + post: operations['respond_to_confirmation_api_conversations__conversation_id__events_respond_to_confirmation_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/search': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Search Conversations + * @description Search / List conversations + */ + get: operations['search_conversations_api_conversations_search_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/count': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Count Conversations + * @description Count conversations matching the given filters + */ + get: operations['count_conversations_api_conversations_count_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Conversation + * @description Given an id, get a conversation + */ + get: operations['get_conversation_api_conversations__conversation_id__get']; + put?: never; + post?: never; + /** + * Delete Conversation + * @description Permanently delete a conversation. + */ + delete: operations['delete_conversation_api_conversations__conversation_id__delete']; + options?: never; + head?: never; + /** + * Update Conversation + * @description Update conversation metadata. + * + * This endpoint allows updating conversation details like title. + */ + patch: operations['update_conversation_api_conversations__conversation_id__patch']; + trace?: never; + }; + '/api/conversations/{conversation_id}/agent_final_response': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Conversation Agent Final Response + * @description Get the agent's final response for a conversation. + * + * Returns the text of the last agent finish message (FinishAction) or + * the last agent text response (MessageEvent). Returns an empty string + * if the agent has not produced a final response yet. + */ + get: operations['get_conversation_agent_final_response_api_conversations__conversation_id__agent_final_response_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Batch Get Conversations + * @description Get a batch of conversations given their ids, returning null for + * any missing item + */ + get: operations['batch_get_conversations_api_conversations_get']; + put?: never; + /** + * Start Conversation + * @description Start a conversation in the local environment. + */ + post: operations['start_conversation_api_conversations_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/pause': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Pause Conversation + * @description Pause a conversation, allowing it to be resumed later. + */ + post: operations['pause_conversation_api_conversations__conversation_id__pause_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/run': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Run Conversation + * @description Start running the conversation in the background. + */ + post: operations['run_conversation_api_conversations__conversation_id__run_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/secrets': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Update Conversation Secrets + * @description Update secrets for a conversation. + */ + post: operations['update_conversation_secrets_api_conversations__conversation_id__secrets_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/confirmation_policy': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Set Conversation Confirmation Policy + * @description Set the confirmation policy for a conversation. + */ + post: operations['set_conversation_confirmation_policy_api_conversations__conversation_id__confirmation_policy_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/security_analyzer': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Set Conversation Security Analyzer + * @description Set the security analyzer for a conversation. + */ + post: operations['set_conversation_security_analyzer_api_conversations__conversation_id__security_analyzer_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/switch_profile': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Switch Conversation Profile + * @description Switch the conversation's LLM profile to a named profile. + */ + post: operations['switch_conversation_profile_api_conversations__conversation_id__switch_profile_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/switch_llm': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Switch Conversation Llm + * @description Swap the conversation's LLM to a caller-supplied object. + * + * Used by app-servers that own the LLM directly and don't push profiles + * to the agent-server's filesystem (see #3017). + */ + post: operations['switch_conversation_llm_api_conversations__conversation_id__switch_llm_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/ask_agent': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Ask Agent + * @description Ask the agent a simple question without affecting conversation state. + */ + post: operations['ask_agent_api_conversations__conversation_id__ask_agent_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/condense': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Condense Conversation + * @description Force condensation of the conversation history. + */ + post: operations['condense_conversation_api_conversations__conversation_id__condense_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/fork': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Fork Conversation + * @description Fork a conversation, deep-copying its event history. + * + * The fork starts in ``idle`` status with a fresh event loop. + * Calling ``run`` on the fork resumes from the copied state, meaning + * the agent has full event memory of the source conversation. + */ + post: operations['fork_conversation_api_conversations__conversation_id__fork_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/acp/conversations/search': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Search Acp Conversations + * @deprecated + * @description Search conversations using the ACP-capable contract. + * + * Deprecated since v1.22.0 and scheduled for removal in v1.27.0. + * Use ``/api/conversations/search`` instead. + */ + get: operations['search_acp_conversations_api_acp_conversations_search_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/acp/conversations/count': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Count Acp Conversations + * @deprecated + * @description Count conversations using the ACP-capable contract. + * + * Deprecated since v1.22.0 and scheduled for removal in v1.27.0. + * Use ``/api/conversations/count`` instead. + */ + get: operations['count_acp_conversations_api_acp_conversations_count_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/acp/conversations/{conversation_id}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Acp Conversation + * @deprecated + * @description Get a conversation using the ACP-capable contract. + * + * Deprecated since v1.22.0 and scheduled for removal in v1.27.0. + * Use ``/api/conversations/{conversation_id}`` instead. + */ + get: operations['get_acp_conversation_api_acp_conversations__conversation_id__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/acp/conversations': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Batch Get Acp Conversations + * @deprecated + * @description Batch get conversations using the ACP-capable contract. + * + * Deprecated since v1.22.0 and scheduled for removal in v1.27.0. + * Use ``/api/conversations`` instead. + */ + get: operations['batch_get_acp_conversations_api_acp_conversations_get']; + put?: never; + /** + * Start Acp Conversation + * @deprecated + * @description Start a conversation using the ACP-capable contract. + * + * Deprecated since v1.22.0 and scheduled for removal in v1.27.0. + * Use ``/api/conversations`` instead; it now accepts ACP agents and + * ``agent_settings`` payloads. + */ + post: operations['start_acp_conversation_api_acp_conversations_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/tools/': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List Available Tools + * @description List all available tools. + */ + get: operations['list_available_tools_api_tools__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/bash/bash_events/search': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Search Bash Events + * @description Search / List bash event events + */ + get: operations['search_bash_events_api_bash_bash_events_search_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/bash/bash_events/{event_id}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Bash Event + * @description Get a bash event event given an id + */ + get: operations['get_bash_event_api_bash_bash_events__event_id__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/bash/bash_events/': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Batch Get Bash Events + * @description Get a batch of bash event events given their ids, returning null for any + * missing item. + */ + get: operations['batch_get_bash_events_api_bash_bash_events__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/bash/start_bash_command': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Start Bash Command + * @description Execute a bash command in the background + */ + post: operations['start_bash_command_api_bash_start_bash_command_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/bash/execute_bash_command': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Execute Bash Command + * @description Execute a bash command and wait for a result + */ + post: operations['execute_bash_command_api_bash_execute_bash_command_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/bash/bash_events': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + post?: never; + /** + * Clear All Bash Events + * @description Clear all bash events from storage + */ + delete: operations['clear_all_bash_events_api_bash_bash_events_delete']; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/git/changes': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Git Changes Query + * @description Get git changes using query parameter (preferred method). + */ + get: operations['git_changes_query_api_git_changes_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/git/diff': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Git Diff Query + * @description Get git diff using query parameter (preferred method). + */ + get: operations['git_diff_query_api_git_diff_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/file/upload': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Upload File Query + * @description Upload a file to the workspace using query parameter (preferred method). + */ + post: operations['upload_file_query_api_file_upload_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/file/download': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Download File Query + * @description Download a file from the workspace using query parameter (preferred method). + */ + get: operations['download_file_query_api_file_download_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/file/home': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Home Directory + * @description Return the agent-server user's home directory and dynamic sidebar lists. + * + * ``favorites`` is the set of visible top-level directories actually present + * in the user's home (so it reflects the real environment instead of a + * hardcoded list of names that may not exist). ``locations`` is the set of + * filesystem roots — '/' on POSIX or available drive letters on Windows. + */ + get: operations['get_home_directory_api_file_home_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/file/search_subdirs': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Search Subdirs + * @description Search / List immediate subdirectories of `path`. + * + * Used by the GUI's workspace picker. Hidden entries (names starting with '.') + * and symlinks are skipped. Files are skipped. Returns absolute paths so the + * GUI can use a result directly as ``workspace.working_dir``. + * + * Results are sorted case-insensitively by name and paginated. ``page_id`` is + * the ``next_page_id`` returned by the previous page (the lowercase name of + * the first item to include on the next page). + */ + get: operations['search_subdirs_api_file_search_subdirs_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/file/download-trajectory/{conversation_id}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Download Trajectory + * @description Download a zip archive of a conversation trajectory. + */ + get: operations['download_trajectory_api_file_download_trajectory__conversation_id__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/vscode/url': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Vscode Url + * @description Get the VSCode URL with authentication token. + * + * Args: + * base_url: Base URL for the VSCode server (default: http://localhost:8001) + * workspace_dir: Path to workspace directory + * + * Returns: + * VSCode URL with token if available, None otherwise + */ + get: operations['get_vscode_url_api_vscode_url_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/vscode/status': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Vscode Status + * @description Get the VSCode server status. + * + * Returns: + * Dictionary with running status and enabled status + */ + get: operations['get_vscode_status_api_vscode_status_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/desktop/url': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Desktop Url + * @description Get the noVNC URL for desktop access. + * + * Args: + * base_url: Base URL for the noVNC server (default: http://localhost:8002) + * + * Returns: + * noVNC URL if available, None otherwise + */ + get: operations['get_desktop_url_api_desktop_url_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/skills': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Get Skills + * @description Load and merge skills from all configured sources. + * + * Skills are loaded from multiple sources and merged with the following + * precedence (later overrides earlier for duplicate names): + * 1. Sandbox skills (lowest) - Exposed URLs from sandbox + * 2. Public skills - From GitHub OpenHands/extensions repository + * 3. User skills - From ~/.openhands/skills/ + * 4. Organization skills - From {org}/.openhands or equivalent + * 5. Project skills (highest) - From {workspace}/.openhands/skills/ + * + * Args: + * request: SkillsRequest containing configuration for which sources to load. + * + * Returns: + * SkillsResponse containing merged skills and source counts. + */ + post: operations['get_skills_api_skills_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/skills/sync': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Sync Skills + * @description Force refresh of public skills from GitHub repository. + * + * This triggers a git pull on the cached skills repository to get + * the latest skills from the OpenHands/extensions repository. + * + * Returns: + * SyncResponse indicating success or failure. + */ + post: operations['sync_skills_api_skills_sync_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/hooks': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Get Hooks + * @description Load hooks from the workspace .openhands/hooks.json file. + * + * This endpoint reads the hooks configuration from the project's + * .openhands/hooks.json file if it exists. + * + * Args: + * request: HooksRequest containing the project directory path. + * + * Returns: + * HooksResponse containing the hook configuration or None. + */ + post: operations['get_hooks_api_hooks_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/llm/providers': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List Providers + * @description List all available LLM providers supported by LiteLLM. + */ + get: operations['list_providers_api_llm_providers_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/llm/models': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List Models + * @description List all available LLM models supported by LiteLLM. + * + * Args: + * provider: Optional provider name to filter models by. + * + * Note: Bedrock models are excluded unless AWS credentials are configured. + */ + get: operations['list_models_api_llm_models_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/llm/models/verified': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List Verified Models + * @description List all verified LLM models organized by provider. + * + * Verified models are those that have been tested and confirmed to work well + * with OpenHands. + */ + get: operations['list_verified_models_api_llm_models_verified_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/settings/agent-schema': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Agent Settings Schema + * @description Return the schema used to render AgentSettings-based settings forms. + */ + get: operations['get_agent_settings_schema_api_settings_agent_schema_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/settings/conversation-schema': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Conversation Settings Schema + * @description Return the schema used to render ConversationSettings-based forms. + */ + get: operations['get_conversation_settings_schema_api_settings_conversation_schema_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/settings': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Settings + * @description Get current settings. + * + * Returns the persisted settings including agent configuration, + * conversation settings, and whether an LLM API key is configured. + * + * Use the ``X-Expose-Secrets`` header to control secret exposure: + * - ``encrypted``: Returns cipher-encrypted values (safe for frontend clients) + * - ``plaintext``: Returns raw secret values (backend clients only!) + * - (absent): Returns redacted values ("**********") + * + * Security: + * When the server is configured with ``session_api_keys``, all endpoints + * under ``/api`` (including this one) require the ``X-Session-API-Key`` + * header. When no session API keys are configured, endpoints are open. + * + * **Trust model:** All authenticated clients are treated as equally + * trusted. There is no role-based authorization for ``X-Expose-Secrets`` + * modes—any authenticated client can request ``plaintext`` or + * ``encrypted`` exposure. This design assumes: + * + * - All clients sharing session API keys operate in the same trust domain + * - Network-level controls (firewalls, VPCs) restrict access to trusted + * clients only + * - Production deployments use session API keys to prevent anonymous access + * + * The ``plaintext`` mode exists for backend-to-backend communication + * (e.g., RemoteWorkspace). Frontend clients should prefer ``encrypted`` + * mode for round-tripping secrets, or omit the header to receive redacted + * values. + */ + get: operations['get_settings_api_settings_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + /** + * Update Settings + * @description Update settings with partial changes. + * + * Accepts ``agent_settings_diff`` and/or ``conversation_settings_diff`` + * for incremental updates. Values are deep-merged with existing settings. + * + * Uses file locking to prevent concurrent updates from overwriting each other. + * + * Raises: + * HTTPException: 400 if the update payload contains invalid values. + */ + patch: operations['update_settings_api_settings_patch']; + trace?: never; + }; + '/api/settings/secrets': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List Secrets + * @description List all available secrets (names and descriptions only, no values). + */ + get: operations['list_secrets_api_settings_secrets_get']; + /** + * Create Secret + * @description Create or update a custom secret (upsert). + * + * Raises: + * HTTPException: 400 if secret name format is invalid, 500 if file is corrupted. + */ + put: operations['create_secret_api_settings_secrets_put']; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/settings/secrets/{name}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Secret Value + * @description Get a single secret value by name. + * + * Returns the raw secret value as plain text. This endpoint is designed + * to be used with LookupSecret for lazy secret resolution. + * + * Raises: + * HTTPException: 400 if name format is invalid, 404 if secret not found. + */ + get: operations['get_secret_value_api_settings_secrets__name__get']; + put?: never; + post?: never; + /** + * Delete Secret + * @description Delete a custom secret by name. + * + * Raises: + * HTTPException: 400 if name format is invalid, 404 if secret not found, + * 500 if file is corrupted. + */ + delete: operations['delete_secret_api_settings_secrets__name__delete']; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/profiles': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * List Profiles + * @description List all saved LLM profiles. + * + * Returns the list of profiles along with the currently active profile name, + * if one has been activated. The active_profile tracks which LLM profile + * configuration is currently in use. + * + * Auto-creates a profile named after the model if: + * - No profiles exist + * - agent_settings.llm has an API key configured + * + * The API key check ensures we only auto-create when the user has actually + * configured their LLM (not just relying on defaults). This allows users + * with existing LLM configurations to see their settings as a profile + * without manual creation. + */ + get: operations['list_profiles_api_profiles_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/profiles/{name}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Get Profile + * @description Get a profile's configuration. + * + * Use the ``X-Expose-Secrets`` header to control secret exposure: + * - ``encrypted``: Returns cipher-encrypted values (safe for frontend clients) + * - ``plaintext``: Returns raw secret values (backend clients only!) + * - (absent): Returns nulled ``api_key`` with ``api_key_set`` indicator + */ + get: operations['get_profile_api_profiles__name__get']; + put?: never; + /** + * Save Profile + * @description Save an LLM configuration as a named profile. + * + * Overwrites an existing profile of the same name. Returns 409 if creating + * a new profile would exceed ``MAX_PROFILES``. + * + * When ``OH_SECRET_KEY`` is configured, secrets are encrypted at rest. + * Clients can submit cipher-encrypted secrets which will be decrypted + * server-side before re-encrypting with the storage cipher. + */ + post: operations['save_profile_api_profiles__name__post']; + /** + * Delete Profile + * @description Delete a saved profile (idempotent). + */ + delete: operations['delete_profile_api_profiles__name__delete']; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/profiles/{name}/rename': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Rename Profile + * @description Rename a saved profile atomically. + * + * Returns 404 if the source does not exist, or 409 if ``new_name`` already + * exists. A same-name rename is a verified no-op (still 404s if missing). + * + * If the renamed profile is the currently active profile, the active_profile + * setting is updated to the new name. + */ + post: operations['rename_profile_api_profiles__name__rename_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/profiles/{name}/activate': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Activate Profile + * @description Activate a saved LLM profile. + * + * This endpoint: + * 1. Loads the named profile's LLM configuration + * 2. Applies it to the current agent settings (updates ``agent_settings.llm``) + * 3. Records the profile name as the active profile for frontend tracking + * + * Returns 404 if the profile does not exist. + * + * Use ``GET /api/profiles`` to see which profile is currently active via + * the ``active_profile`` field. + */ + post: operations['activate_profile_api_profiles__name__activate_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/cloud-proxy': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** Cloud Proxy */ + post: operations['cloud_proxy_api_cloud_proxy_post']; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/auth/workspace-session': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** + * Create Workspace Session + * @description Mint a workspace-scoped session cookie. + * + * Caller must already be authenticated by the ``X-Session-API-Key`` + * header (enforced by the parent router's dependency). The cookie value + * is the validated session API key itself; it is HttpOnly so JS in + * workspace HTML cannot read it back. + */ + post: operations['create_workspace_session_api_auth_workspace_session_post']; + /** + * Delete Workspace Session + * @description Clear the workspace session cookie. + * + * Browsers identify cookies by ``(name, domain, path)``; the deletion + * cookie must therefore share the original cookie's attributes. We + * overwrite with an empty value and ``max_age=0`` so the browser drops + * it immediately. + */ + delete: operations['delete_workspace_session_api_auth_workspace_session_delete']; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/workspace': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Serve Workspace Root + * @description Serve ``index.html`` from the conversation's workspace root. + */ + get: operations['serve_workspace_root_api_conversations__conversation_id__workspace_get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/api/conversations/{conversation_id}/workspace/{file_path}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** + * Serve Workspace File + * @description Serve a file (or directory ``index.html``) from the workspace. + */ + get: operations['serve_workspace_file_api_conversations__conversation_id__workspace__file_path__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** Get Server Info */ + get: operations['get_server_info__get']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; +}; +export type webhooks = Record; +export type components = { + schemas: { + /** + * ACPAgent + * @description Agent that delegates to an ACP-compatible subprocess server. + */ + 'ACPAgent-Input': { + llm?: components['schemas']['LLM-Input']; + /** Tools */ + tools?: components['schemas']['Tool-Input'][]; + /** + * Mcp Config + * @description Optional MCP configuration dictionary to create MCP tools. + * @example { + * "mcpServers": { + * "fetch": { + * "args": [ + * "mcp-server-fetch" + * ], + * "command": "uvx" + * } + * } + * } + */ + mcp_config?: { + [key: string]: unknown; + }; + /** + * Filter Tools Regex + * @description Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added. + * @example ^(?!repomix)(.*)|^repomix.*pack_codebase.*$ + */ + filter_tools_regex?: string | null; + /** Include Default Tools */ + include_default_tools?: string[]; + /** + * @description Optional AgentContext to initialize the agent with specific context. + * @example { + * "skills": [ + * { + * "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + * "name": "AGENTS.md", + * "type": "repo" + * }, + * { + * "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + * "name": "flarglebargle", + * "trigger": [ + * "flarglebargle" + * ], + * "type": "knowledge" + * } + * ], + * "system_message_suffix": "Always finish your response with the word 'yay!'", + * "user_message_prefix": "The first character of your response should be 'I'" + * } + */ + agent_context?: components['schemas']['AgentContext-Input'] | null; + /** + * System Prompt + * @description Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`. + * + * **Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour. + */ + system_prompt?: string | null; + /** + * System Prompt Filename + * @description System prompt template filename. Can be either: + * - A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_prompt.j2') + * @default system_prompt.j2 + */ + system_prompt_filename?: string; + /** + * Security Policy Filename + * @description Security policy template filename. Can be either: + * - A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_security_policy.j2') + * - Empty string to disable security policy + * @default security_policy.j2 + */ + security_policy_filename?: string; + /** + * System Prompt Kwargs + * @description Optional kwargs to pass to the system prompt Jinja2 template. + * @example { + * "cli_mode": true + * } + */ + system_prompt_kwargs?: { + [key: string]: unknown; + }; + /** + * @description Optional condenser to use for condensing conversation history. + * @example { + * "keep_first": 10, + * "kind": "LLMSummarizingCondenser", + * "llm": { + * "api_key": "your_api_key_here", + * "base_url": "https://llm-proxy.eval.all-hands.dev", + * "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + * }, + * "max_size": 80 + * } + */ + condenser?: components['schemas']['CondenserBase-Input'] | null; + /** + * @description EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode. + * @example { + * "kind": "AgentFinishedCritic" + * } + */ + critic?: components['schemas']['CriticBase-Input'] | null; + /** + * Tool Concurrency Limit + * @description Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race. + * @default 1 + */ + tool_concurrency_limit?: number; + /** + * Acp Command + * @description Command to start the ACP server, e.g. ['npx', '-y', '@agentclientprotocol/claude-agent-acp'] + */ + acp_command: string[]; + /** + * Acp Args + * @description Additional arguments for the ACP server command + */ + acp_args?: string[]; + /** + * Acp Env + * @description Additional environment variables for the ACP server process + */ + acp_env?: { + [key: string]: string; + }; + /** + * Acp Session Mode + * @description Session mode ID to set after creating a session. If None (default), auto-detected from the ACP server type: 'bypassPermissions' for claude-agent-acp, 'full-access' for codex-acp. + */ + acp_session_mode?: string | null; + /** + * Acp Prompt Timeout + * @description Timeout in seconds for a single ACP prompt() call. Prevents indefinite hangs when the ACP server fails to respond. + * @default 1800 + */ + acp_prompt_timeout?: number; + /** + * Acp Model + * @description Model for the ACP server to use (e.g. 'claude-opus-4-6' or 'gpt-5.4'). For Claude ACP, passed via session _meta. For Codex ACP, applied via the protocol-level set_session_model call. If None, the server picks its default. + */ + acp_model?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__agent__acp_agent__ACPAgent-Input__1'; + }; + /** + * ACPAgent + * @description Agent that delegates to an ACP-compatible subprocess server. + */ + 'ACPAgent-Output': { + llm?: components['schemas']['LLM-Output']; + /** Tools */ + tools?: components['schemas']['openhands__sdk__tool__spec__Tool'][]; + /** + * Mcp Config + * @description Optional MCP configuration dictionary to create MCP tools. + * @example { + * "mcpServers": { + * "fetch": { + * "args": [ + * "mcp-server-fetch" + * ], + * "command": "uvx" + * } + * } + * } + */ + mcp_config?: { + [key: string]: unknown; + }; + /** + * Filter Tools Regex + * @description Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added. + * @example ^(?!repomix)(.*)|^repomix.*pack_codebase.*$ + */ + filter_tools_regex?: string | null; + /** Include Default Tools */ + include_default_tools?: string[]; + /** + * @description Optional AgentContext to initialize the agent with specific context. + * @example { + * "skills": [ + * { + * "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + * "name": "AGENTS.md", + * "type": "repo" + * }, + * { + * "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + * "name": "flarglebargle", + * "trigger": [ + * "flarglebargle" + * ], + * "type": "knowledge" + * } + * ], + * "system_message_suffix": "Always finish your response with the word 'yay!'", + * "user_message_prefix": "The first character of your response should be 'I'" + * } + */ + agent_context?: components['schemas']['AgentContext-Output'] | null; + /** + * System Prompt + * @description Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`. + * + * **Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour. + */ + system_prompt?: string | null; + /** + * System Prompt Filename + * @description System prompt template filename. Can be either: + * - A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_prompt.j2') + * @default system_prompt.j2 + */ + system_prompt_filename?: string; + /** + * Security Policy Filename + * @description Security policy template filename. Can be either: + * - A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_security_policy.j2') + * - Empty string to disable security policy + * @default security_policy.j2 + */ + security_policy_filename?: string; + /** + * System Prompt Kwargs + * @description Optional kwargs to pass to the system prompt Jinja2 template. + * @example { + * "cli_mode": true + * } + */ + system_prompt_kwargs?: { + [key: string]: unknown; + }; + /** + * @description Optional condenser to use for condensing conversation history. + * @example { + * "keep_first": 10, + * "kind": "LLMSummarizingCondenser", + * "llm": { + * "api_key": "your_api_key_here", + * "base_url": "https://llm-proxy.eval.all-hands.dev", + * "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + * }, + * "max_size": 80 + * } + */ + condenser?: components['schemas']['CondenserBase-Output'] | null; + /** + * @description EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode. + * @example { + * "kind": "AgentFinishedCritic" + * } + */ + critic?: components['schemas']['CriticBase-Output'] | null; + /** + * Tool Concurrency Limit + * @description Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race. + * @default 1 + */ + tool_concurrency_limit?: number; + /** + * Acp Command + * @description Command to start the ACP server, e.g. ['npx', '-y', '@agentclientprotocol/claude-agent-acp'] + */ + acp_command: string[]; + /** + * Acp Args + * @description Additional arguments for the ACP server command + */ + acp_args?: string[]; + /** + * Acp Env + * @description Additional environment variables for the ACP server process + */ + acp_env?: { + [key: string]: string; + }; + /** + * Acp Session Mode + * @description Session mode ID to set after creating a session. If None (default), auto-detected from the ACP server type: 'bypassPermissions' for claude-agent-acp, 'full-access' for codex-acp. + */ + acp_session_mode?: string | null; + /** + * Acp Prompt Timeout + * @description Timeout in seconds for a single ACP prompt() call. Prevents indefinite hangs when the ACP server fails to respond. + * @default 1800 + */ + acp_prompt_timeout?: number; + /** + * Acp Model + * @description Model for the ACP server to use (e.g. 'claude-opus-4-6' or 'gpt-5.4'). For Claude ACP, passed via session _meta. For Codex ACP, applied via the protocol-level set_session_model call. If None, the server picks its default. + */ + acp_model?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__agent__acp_agent__ACPAgent-Output__1'; + }; + /** + * ACPToolCallEvent + * @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. + */ + ACPToolCallEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default agent + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** Tool Call Id */ + tool_call_id: string; + /** Title */ + title: string; + /** Status */ + status?: string | null; + /** Tool Kind */ + tool_kind?: string | null; + /** Raw Input */ + raw_input?: unknown | null; + /** Raw Output */ + raw_output?: unknown | null; + /** Content */ + content?: unknown[] | null; + /** + * Is Error + * @default false + */ + is_error?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__acp_tool_call__ACPToolCallEvent-Output__1'; + }; + /** APIBasedCritic */ + 'APIBasedCritic-Input': { + /** + * Server Url + * @description Base URL of the vLLM classification service + * @default https://llm-proxy.app.all-hands.dev/vllm + */ + server_url?: string; + /** + * Api Key + * @description API key for authenticating with the vLLM service + */ + api_key: string; + /** + * Model Name + * @description Name of the model to use + * @default critic + */ + model_name?: string; + /** + * Tokenizer Name + * @description HuggingFace tokenizer name for loading chat template + * @default Qwen/Qwen3-4B-Instruct-2507 + */ + tokenizer_name?: string; + /** + * Pass Tools Definitions + * @description Whether to pass tool definitions to the model + * @default true + */ + pass_tools_definitions?: boolean; + /** + * Timeout Seconds + * @description Timeout for requests to the model + * @default 300 + */ + timeout_seconds?: number; + /** + * Has Success Label + * @description Whether the model predicts success label at index 0 + * @default true + */ + has_success_label?: boolean; + /** + * Sentiment Labels + * @default [ + * "sentiment_positive", + * "sentiment_neutral", + * "sentiment_negative" + * ] + */ + sentiment_labels?: string[]; + /** + * Agent Issue Labels + * @default [ + * "misunderstood_intention", + * "did_not_follow_instruction", + * "insufficient_analysis", + * "insufficient_clarification", + * "improper_tool_use_or_setup", + * "loop_behavior", + * "insufficient_testing", + * "insufficient_debugging", + * "incomplete_implementation", + * "file_management_errors", + * "scope_creep", + * "risky_actions_or_permission", + * "other_agent_issue" + * ] + */ + agent_issue_labels?: string[]; + /** + * Infra Labels + * @default [ + * "infrastructure_external_issue", + * "infrastructure_agent_caused_issue" + * ] + */ + infra_labels?: string[]; + /** + * User Followup Labels + * @default [ + * "clarification_or_restatement", + * "correction", + * "direction_change", + * "vcs_update_requests", + * "progress_or_scope_concern", + * "frustration_or_complaint", + * "removal_or_reversion_request", + * "other_user_issue" + * ] + */ + user_followup_labels?: string[]; + /** + * Sentiment Map + * @default { + * "Positive": "sentiment_positive", + * "Neutral": "sentiment_neutral", + * "Negative": "sentiment_negative" + * } + */ + sentiment_map?: { + [key: string]: string; + }; + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * Issue Threshold + * @description APIBasedCritic-specific probability threshold for agent issue labels that should trigger iterative refinement. + * @default 0.75 + */ + issue_threshold?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__api__critic__APIBasedCritic-Input__1'; + }; + /** APIBasedCritic */ + 'APIBasedCritic-Output': { + /** + * Server Url + * @description Base URL of the vLLM classification service + * @default https://llm-proxy.app.all-hands.dev/vllm + */ + server_url?: string; + /** + * Api Key + * @description API key for authenticating with the vLLM service + */ + api_key: string; + /** + * Model Name + * @description Name of the model to use + * @default critic + */ + model_name?: string; + /** + * Tokenizer Name + * @description HuggingFace tokenizer name for loading chat template + * @default Qwen/Qwen3-4B-Instruct-2507 + */ + tokenizer_name?: string; + /** + * Pass Tools Definitions + * @description Whether to pass tool definitions to the model + * @default true + */ + pass_tools_definitions?: boolean; + /** + * Timeout Seconds + * @description Timeout for requests to the model + * @default 300 + */ + timeout_seconds?: number; + /** + * Has Success Label + * @description Whether the model predicts success label at index 0 + * @default true + */ + has_success_label?: boolean; + /** + * Sentiment Labels + * @default [ + * "sentiment_positive", + * "sentiment_neutral", + * "sentiment_negative" + * ] + */ + sentiment_labels?: string[]; + /** + * Agent Issue Labels + * @default [ + * "misunderstood_intention", + * "did_not_follow_instruction", + * "insufficient_analysis", + * "insufficient_clarification", + * "improper_tool_use_or_setup", + * "loop_behavior", + * "insufficient_testing", + * "insufficient_debugging", + * "incomplete_implementation", + * "file_management_errors", + * "scope_creep", + * "risky_actions_or_permission", + * "other_agent_issue" + * ] + */ + agent_issue_labels?: string[]; + /** + * Infra Labels + * @default [ + * "infrastructure_external_issue", + * "infrastructure_agent_caused_issue" + * ] + */ + infra_labels?: string[]; + /** + * User Followup Labels + * @default [ + * "clarification_or_restatement", + * "correction", + * "direction_change", + * "vcs_update_requests", + * "progress_or_scope_concern", + * "frustration_or_complaint", + * "removal_or_reversion_request", + * "other_user_issue" + * ] + */ + user_followup_labels?: string[]; + /** + * Sentiment Map + * @default { + * "Positive": "sentiment_positive", + * "Neutral": "sentiment_neutral", + * "Negative": "sentiment_negative" + * } + */ + sentiment_map?: { + [key: string]: string; + }; + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * Issue Threshold + * @description APIBasedCritic-specific probability threshold for agent issue labels that should trigger iterative refinement. + * @default 0.75 + */ + issue_threshold?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__api__critic__APIBasedCritic-Output__1'; + }; + Action: + | components['schemas']['BrowserActionWithRisk'] + | components['schemas']['BrowserClickActionWithRisk'] + | components['schemas']['BrowserCloseTabActionWithRisk'] + | components['schemas']['BrowserGetContentActionWithRisk'] + | components['schemas']['BrowserGetStateActionWithRisk'] + | components['schemas']['BrowserGetStorageActionWithRisk'] + | components['schemas']['BrowserGoBackActionWithRisk'] + | components['schemas']['BrowserListTabsActionWithRisk'] + | components['schemas']['BrowserNavigateActionWithRisk'] + | components['schemas']['BrowserScrollActionWithRisk'] + | components['schemas']['BrowserSetStorageActionWithRisk'] + | components['schemas']['BrowserStartRecordingActionWithRisk'] + | components['schemas']['BrowserStopRecordingActionWithRisk'] + | components['schemas']['BrowserSwitchTabActionWithRisk'] + | components['schemas']['BrowserTypeActionWithRisk'] + | components['schemas']['DelegateActionWithRisk'] + | components['schemas']['EditActionWithRisk'] + | components['schemas']['FileEditorActionWithRisk'] + | components['schemas']['FinishActionWithRisk'] + | components['schemas']['GlobActionWithRisk'] + | components['schemas']['GrepActionWithRisk'] + | components['schemas']['InvokeSkillActionWithRisk'] + | components['schemas']['ListDirectoryActionWithRisk'] + | components['schemas']['MCPToolActionWithRisk'] + | components['schemas']['PlanningFileEditorActionWithRisk'] + | components['schemas']['ReadFileActionWithRisk'] + | components['schemas']['SwitchLLMActionWithRisk'] + | components['schemas']['TaskActionWithRisk'] + | components['schemas']['TaskTrackerActionWithRisk'] + | components['schemas']['TerminalActionWithRisk'] + | components['schemas']['ThinkActionWithRisk'] + | components['schemas']['WriteFileActionWithRisk'] + | components['schemas']['MCPToolAction'] + | components['schemas']['FinishAction'] + | components['schemas']['InvokeSkillAction'] + | components['schemas']['SwitchLLMAction'] + | components['schemas']['ThinkAction'] + | components['schemas']['BrowserAction'] + | components['schemas']['BrowserClickAction'] + | components['schemas']['BrowserCloseTabAction'] + | components['schemas']['BrowserGetContentAction'] + | components['schemas']['BrowserGetStateAction'] + | components['schemas']['BrowserGetStorageAction'] + | components['schemas']['BrowserGoBackAction'] + | components['schemas']['BrowserListTabsAction'] + | components['schemas']['BrowserNavigateAction'] + | components['schemas']['BrowserScrollAction'] + | components['schemas']['BrowserSetStorageAction'] + | components['schemas']['BrowserStartRecordingAction'] + | components['schemas']['BrowserStopRecordingAction'] + | components['schemas']['BrowserSwitchTabAction'] + | components['schemas']['BrowserTypeAction'] + | components['schemas']['DelegateAction'] + | components['schemas']['FileEditorAction'] + | components['schemas']['EditAction'] + | components['schemas']['ListDirectoryAction'] + | components['schemas']['ReadFileAction'] + | components['schemas']['WriteFileAction'] + | components['schemas']['GlobAction'] + | components['schemas']['GrepAction'] + | components['schemas']['PlanningFileEditorAction'] + | components['schemas']['TaskAction'] + | components['schemas']['TaskTrackerAction'] + | components['schemas']['TerminalAction']; + /** ActionEvent */ + ActionEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default agent + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Thought + * @description The thought process of the agent before taking this action + */ + thought: components['schemas']['TextContent'][]; + /** + * Reasoning Content + * @description Intermediate reasoning/thinking content from reasoning models + */ + reasoning_content?: string | null; + /** + * Thinking Blocks + * @description Anthropic thinking blocks from the LLM response + */ + thinking_blocks?: ( + | components['schemas']['ThinkingBlock'] + | components['schemas']['RedactedThinkingBlock'] + )[]; + /** @description OpenAI Responses reasoning item from model output */ + responses_reasoning_item?: components['schemas']['ReasoningItemModel'] | null; + /** @description Single tool call returned by LLM (None when non-executable) */ + action?: components['schemas']['Action'] | null; + /** + * Tool Name + * @description The name of the tool being called + */ + tool_name: string; + /** + * Tool Call Id + * @description The unique id returned by LLM API for this tool call + */ + tool_call_id: string; + /** @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: components['schemas']['MessageToolCall']; + /** + * 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. + */ + llm_response_id: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** @description Optional critic evaluation of this action and preceding history. */ + critic_result?: components['schemas']['CriticResult'] | null; + /** + * Summary + * @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' + */ + summary?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_convertible__action__ActionEvent-Output__1'; + }; + /** + * ActivateProfileResponse + * @description Response model for profile activation. + */ + ActivateProfileResponse: { + /** Name */ + name: string; + /** Message */ + message: string; + /** + * Llm Applied + * @default true + */ + llm_applied?: boolean; + }; + /** + * Agent + * @description Main agent implementation for OpenHands. + * + * The Agent class provides the core functionality for running AI agents that can + * interact with tools, process messages, and execute actions. It inherits from + * AgentBase and implements the agent execution logic. Critic-related functionality + * is provided by CriticMixin. + * + * Attributes: + * llm: The language model instance used for reasoning. + * tools: List of tools available to the agent. + * system_prompt: Inline system prompt string. When provided the agent + * uses this text verbatim instead of rendering from a template. + * Mutually exclusive with a non-default ``system_prompt_filename``. + * **Not recommended** unless you know what you are doing (e.g. + * customising agent behaviour for a completely different task) — + * this will override OpenHands' built-in system instructions. + * system_prompt_filename: Jinja2 template filename resolved relative to + * the agent's prompts directory, or an absolute path. Defaults to + * ``"system_prompt.j2"``. + * system_prompt_kwargs: Extra kwargs forwarded to the Jinja2 template. + * + * Example: + * ```python + * from openhands.sdk import LLM, Agent, Tool + * from pydantic import SecretStr + * + * llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key")) + * tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")] + * agent = Agent(llm=llm, tools=tools) + * ``` + * + * To override the system prompt entirely:: + * + * agent = Agent( + * llm=llm, + * tools=tools, + * system_prompt="You are a helpful coding assistant.", + * ) + */ + 'Agent-Input': { + /** + * @description LLM configuration for the agent. + * @example { + * "api_key": "your_api_key_here", + * "base_url": "https://llm-proxy.eval.all-hands.dev", + * "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + * } + */ + llm: components['schemas']['LLM-Input']; + /** + * Tools + * @description List of tools to initialize for the agent. + * @example { + * "name": "TerminalTool", + * "params": {} + * } + * @example { + * "name": "FileEditorTool", + * "params": {} + * } + * @example { + * "name": "TaskTrackerTool", + * "params": {} + * } + */ + tools?: components['schemas']['Tool-Input'][]; + /** + * Mcp Config + * @description Optional MCP configuration dictionary to create MCP tools. + * @example { + * "mcpServers": { + * "fetch": { + * "args": [ + * "mcp-server-fetch" + * ], + * "command": "uvx" + * } + * } + * } + */ + mcp_config?: { + [key: string]: unknown; + }; + /** + * Filter Tools Regex + * @description Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added. + * @example ^(?!repomix)(.*)|^repomix.*pack_codebase.*$ + */ + filter_tools_regex?: string | null; + /** + * Include Default Tools + * @description List of default tool class names to include. By default, the agent includes 'FinishTool' and 'ThinkTool'. Set to an empty list to disable all default tools, or provide a subset to include only specific ones. Example: include_default_tools=['FinishTool'] to only include FinishTool, or include_default_tools=[] to disable all default tools. + * @example [ + * "FinishTool", + * "ThinkTool" + * ] + * @example [ + * "FinishTool" + * ] + * @example [] + */ + include_default_tools?: string[]; + /** + * @description Optional AgentContext to initialize the agent with specific context. + * @example { + * "skills": [ + * { + * "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + * "name": "AGENTS.md", + * "type": "repo" + * }, + * { + * "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + * "name": "flarglebargle", + * "trigger": [ + * "flarglebargle" + * ], + * "type": "knowledge" + * } + * ], + * "system_message_suffix": "Always finish your response with the word 'yay!'", + * "user_message_prefix": "The first character of your response should be 'I'" + * } + */ + agent_context?: components['schemas']['AgentContext-Input'] | null; + /** + * System Prompt + * @description Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`. + * + * **Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour. + */ + system_prompt?: string | null; + /** + * System Prompt Filename + * @description System prompt template filename. Can be either: + * - A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_prompt.j2') + * @default system_prompt.j2 + */ + system_prompt_filename?: string; + /** + * Security Policy Filename + * @description Security policy template filename. Can be either: + * - A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_security_policy.j2') + * - Empty string to disable security policy + * @default security_policy.j2 + */ + security_policy_filename?: string; + /** + * System Prompt Kwargs + * @description Optional kwargs to pass to the system prompt Jinja2 template. + * @example { + * "cli_mode": true + * } + */ + system_prompt_kwargs?: { + [key: string]: unknown; + }; + /** + * @description Optional condenser to use for condensing conversation history. + * @example { + * "keep_first": 10, + * "kind": "LLMSummarizingCondenser", + * "llm": { + * "api_key": "your_api_key_here", + * "base_url": "https://llm-proxy.eval.all-hands.dev", + * "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + * }, + * "max_size": 80 + * } + */ + condenser?: components['schemas']['CondenserBase-Input'] | null; + /** + * @description EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode. + * @example { + * "kind": "AgentFinishedCritic" + * } + */ + critic?: components['schemas']['CriticBase-Input'] | null; + /** + * Tool Concurrency Limit + * @description Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race. + * @default 1 + */ + tool_concurrency_limit?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__agent__agent__Agent-Input__1'; + }; + /** + * Agent + * @description Main agent implementation for OpenHands. + * + * The Agent class provides the core functionality for running AI agents that can + * interact with tools, process messages, and execute actions. It inherits from + * AgentBase and implements the agent execution logic. Critic-related functionality + * is provided by CriticMixin. + * + * Attributes: + * llm: The language model instance used for reasoning. + * tools: List of tools available to the agent. + * system_prompt: Inline system prompt string. When provided the agent + * uses this text verbatim instead of rendering from a template. + * Mutually exclusive with a non-default ``system_prompt_filename``. + * **Not recommended** unless you know what you are doing (e.g. + * customising agent behaviour for a completely different task) — + * this will override OpenHands' built-in system instructions. + * system_prompt_filename: Jinja2 template filename resolved relative to + * the agent's prompts directory, or an absolute path. Defaults to + * ``"system_prompt.j2"``. + * system_prompt_kwargs: Extra kwargs forwarded to the Jinja2 template. + * + * Example: + * ```python + * from openhands.sdk import LLM, Agent, Tool + * from pydantic import SecretStr + * + * llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key")) + * tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")] + * agent = Agent(llm=llm, tools=tools) + * ``` + * + * To override the system prompt entirely:: + * + * agent = Agent( + * llm=llm, + * tools=tools, + * system_prompt="You are a helpful coding assistant.", + * ) + */ + 'Agent-Output': { + /** + * @description LLM configuration for the agent. + * @example { + * "api_key": "your_api_key_here", + * "base_url": "https://llm-proxy.eval.all-hands.dev", + * "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + * } + */ + llm: components['schemas']['LLM-Output']; + /** + * Tools + * @description List of tools to initialize for the agent. + * @example { + * "name": "TerminalTool", + * "params": {} + * } + * @example { + * "name": "FileEditorTool", + * "params": {} + * } + * @example { + * "name": "TaskTrackerTool", + * "params": {} + * } + */ + tools?: components['schemas']['openhands__sdk__tool__spec__Tool'][]; + /** + * Mcp Config + * @description Optional MCP configuration dictionary to create MCP tools. + * @example { + * "mcpServers": { + * "fetch": { + * "args": [ + * "mcp-server-fetch" + * ], + * "command": "uvx" + * } + * } + * } + */ + mcp_config?: { + [key: string]: unknown; + }; + /** + * Filter Tools Regex + * @description Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added. + * @example ^(?!repomix)(.*)|^repomix.*pack_codebase.*$ + */ + filter_tools_regex?: string | null; + /** + * Include Default Tools + * @description List of default tool class names to include. By default, the agent includes 'FinishTool' and 'ThinkTool'. Set to an empty list to disable all default tools, or provide a subset to include only specific ones. Example: include_default_tools=['FinishTool'] to only include FinishTool, or include_default_tools=[] to disable all default tools. + * @example [ + * "FinishTool", + * "ThinkTool" + * ] + * @example [ + * "FinishTool" + * ] + * @example [] + */ + include_default_tools?: string[]; + /** + * @description Optional AgentContext to initialize the agent with specific context. + * @example { + * "skills": [ + * { + * "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + * "name": "AGENTS.md", + * "type": "repo" + * }, + * { + * "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + * "name": "flarglebargle", + * "trigger": [ + * "flarglebargle" + * ], + * "type": "knowledge" + * } + * ], + * "system_message_suffix": "Always finish your response with the word 'yay!'", + * "user_message_prefix": "The first character of your response should be 'I'" + * } + */ + agent_context?: components['schemas']['AgentContext-Output'] | null; + /** + * System Prompt + * @description Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`. + * + * **Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour. + */ + system_prompt?: string | null; + /** + * System Prompt Filename + * @description System prompt template filename. Can be either: + * - A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_prompt.j2') + * @default system_prompt.j2 + */ + system_prompt_filename?: string; + /** + * Security Policy Filename + * @description Security policy template filename. Can be either: + * - A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory + * - An absolute path (e.g., '/path/to/custom_security_policy.j2') + * - Empty string to disable security policy + * @default security_policy.j2 + */ + security_policy_filename?: string; + /** + * System Prompt Kwargs + * @description Optional kwargs to pass to the system prompt Jinja2 template. + * @example { + * "cli_mode": true + * } + */ + system_prompt_kwargs?: { + [key: string]: unknown; + }; + /** + * @description Optional condenser to use for condensing conversation history. + * @example { + * "keep_first": 10, + * "kind": "LLMSummarizingCondenser", + * "llm": { + * "api_key": "your_api_key_here", + * "base_url": "https://llm-proxy.eval.all-hands.dev", + * "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + * }, + * "max_size": 80 + * } + */ + condenser?: components['schemas']['CondenserBase-Output'] | null; + /** + * @description EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode. + * @example { + * "kind": "AgentFinishedCritic" + * } + */ + critic?: components['schemas']['CriticBase-Output'] | null; + /** + * Tool Concurrency Limit + * @description Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race. + * @default 1 + */ + tool_concurrency_limit?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__agent__agent__Agent-Output__1'; + }; + 'AgentBase-Input': + | components['schemas']['ACPAgent-Input'] + | components['schemas']['Agent-Input']; + 'AgentBase-Output': + | components['schemas']['ACPAgent-Output'] + | components['schemas']['Agent-Output']; + /** + * AgentContext + * @description Central structure for managing prompt extension. + * + * AgentContext unifies all the contextual inputs that shape how the system + * extends and interprets user prompts. It combines both static environment + * details and dynamic, user-activated extensions from skills. + * + * Specifically, it provides: + * - **Repository context / Repo Skills**: Information about the active codebase, + * branches, and repo-specific instructions contributed by repo skills. + * - **Runtime context**: Current execution environment (hosts, working + * directory, secrets, date, etc.). + * - **Conversation instructions**: Optional task- or channel-specific rules + * that constrain or guide the agent’s behavior across the session. + * - **Knowledge Skills**: Extensible components that can be triggered by user input + * to inject knowledge or domain-specific guidance. + * + * Together, these elements make AgentContext the primary container responsible + * for assembling, formatting, and injecting all prompt-relevant context into + * LLM interactions. + */ + 'AgentContext-Input': { + /** + * Skills + * @description List of available skills that can extend the user's input. + */ + skills?: components['schemas']['Skill'][]; + /** + * System Message Suffix + * @description Optional suffix to append to the system prompt. + */ + system_message_suffix?: string | null; + /** + * User Message Suffix + * @description Optional suffix to append to the user's message. + */ + user_message_suffix?: string | null; + /** + * Load User Skills + * @description Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). + * @default false + */ + load_user_skills?: boolean; + /** + * Load Public Skills + * @description Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/extensions. This allows you to get the latest skills without SDK updates. + * @default false + */ + load_public_skills?: boolean; + /** + * Marketplace Path + * @description Relative marketplace JSON path within the public skills repository. Set to None to load all public skills without marketplace filtering. + * @default marketplaces/default.json + */ + marketplace_path?: string | null; + /** + * Secrets + * @description Dictionary mapping secret keys to values or secret sources. Secrets are used for authentication and sensitive data handling. Values can be either strings or SecretSource instances (str | SecretSource). + */ + secrets?: { + [key: string]: string | components['schemas']['SecretSource-Input']; + } | null; + /** + * Current Datetime + * @description Current date and time information to provide to the agent. Can be a datetime object (which will be formatted as ISO 8601) or a pre-formatted string. When provided, this information is included in the system prompt to give the agent awareness of the current time context. Defaults to the current datetime. + */ + current_datetime?: string | null; + }; + /** + * AgentContext + * @description Central structure for managing prompt extension. + * + * AgentContext unifies all the contextual inputs that shape how the system + * extends and interprets user prompts. It combines both static environment + * details and dynamic, user-activated extensions from skills. + * + * Specifically, it provides: + * - **Repository context / Repo Skills**: Information about the active codebase, + * branches, and repo-specific instructions contributed by repo skills. + * - **Runtime context**: Current execution environment (hosts, working + * directory, secrets, date, etc.). + * - **Conversation instructions**: Optional task- or channel-specific rules + * that constrain or guide the agent’s behavior across the session. + * - **Knowledge Skills**: Extensible components that can be triggered by user input + * to inject knowledge or domain-specific guidance. + * + * Together, these elements make AgentContext the primary container responsible + * for assembling, formatting, and injecting all prompt-relevant context into + * LLM interactions. + */ + 'AgentContext-Output': { + /** + * Skills + * @description List of available skills that can extend the user's input. + */ + skills?: components['schemas']['Skill'][]; + /** + * System Message Suffix + * @description Optional suffix to append to the system prompt. + */ + system_message_suffix?: string | null; + /** + * User Message Suffix + * @description Optional suffix to append to the user's message. + */ + user_message_suffix?: string | null; + /** + * Load User Skills + * @description Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). + * @default false + */ + load_user_skills?: boolean; + /** + * Load Public Skills + * @description Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/extensions. This allows you to get the latest skills without SDK updates. + * @default false + */ + load_public_skills?: boolean; + /** + * Marketplace Path + * @description Relative marketplace JSON path within the public skills repository. Set to None to load all public skills without marketplace filtering. + * @default marketplaces/default.json + */ + marketplace_path?: string | null; + /** + * Secrets + * @description Dictionary mapping secret keys to values or secret sources. Secrets are used for authentication and sensitive data handling. Values can be either strings or SecretSource instances (str | SecretSource). + */ + secrets?: { + [key: string]: unknown; + } | null; + /** + * Current Datetime + * @description Current date and time information to provide to the agent. Can be a datetime object (which will be formatted as ISO 8601) or a pre-formatted string. When provided, this information is included in the system prompt to give the agent awareness of the current time context. Defaults to the current datetime. + */ + current_datetime?: string | null; + }; + /** + * AgentDefinition + * @description Agent definition loaded from Markdown file. + * + * Agents are specialized configurations that can be triggered based on + * user input patterns. They define custom system prompts and tool access. + */ + AgentDefinition: { + /** + * Name + * @description Agent name (from frontmatter or filename) + */ + name: string; + /** + * Description + * @description Agent description + * @default + */ + description?: string; + /** + * Model + * @description Model to use ('inherit' uses parent model) + * @default inherit + */ + model?: string; + /** + * Color + * @description Display color for the agent + */ + color?: string | null; + /** + * Tools + * @description List of allowed tools for this agent + */ + tools?: string[]; + /** + * Skills + * @description List of skill names for this agent. Resolved from project/user directories. + */ + skills?: string[]; + /** + * System Prompt + * @description System prompt content + * @default + */ + system_prompt?: string; + /** + * Source + * @description Source file path for this agent + */ + source?: string | null; + /** + * When To Use Examples + * @description Examples of when to use this agent (for triggering) + */ + when_to_use_examples?: string[]; + /** @description Hook configuration for this agent */ + hooks?: components['schemas']['HookConfig-Input'] | null; + /** + * Permission Mode + * @description How the subagent handles permissions. None inherits the parent policy, 'always_confirm' requires confirmation for every action, 'never_confirm' skips all confirmations, 'confirm_risky' only confirms actions above a risk threshold. + */ + permission_mode?: string | null; + /** + * Max Iteration Per Run + * @description Maximum iterations per run. It must be strictly positive, or None for default. + */ + max_iteration_per_run?: number | null; + /** + * Mcp Servers + * @description MCP server configurations for this agent. Keys are server names, values are server configs with 'command', 'args', etc. + * @example { + * "fetch": { + * "args": [ + * "mcp-server-fetch" + * ], + * "command": "uvx" + * } + * } + */ + mcp_servers?: { + [key: string]: unknown; + } | null; + /** + * Profile Store Dir + * @description Path to the directory where LLM profiles are stored. If None, the default profile store directory is used. + */ + profile_store_dir?: string | null; + /** + * Metadata + * @description Additional metadata from frontmatter + */ + metadata?: { + [key: string]: unknown; + }; + }; + /** + * AgentErrorEvent + * @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. + */ + AgentErrorEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default agent + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Tool Name + * @description The tool name that this observation is responding to + */ + tool_name: string; + /** + * Tool Call Id + * @description The tool call id that this observation is responding to + */ + tool_call_id: string; + /** + * Error + * @description The error message from the scaffold + */ + error: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_convertible__observation__AgentErrorEvent-Output__1'; + }; + /** + * AgentFinishedCritic + * @description Critic that evaluates whether an agent properly finished a task. + * + * This critic checks two main criteria: + * 1. The agent's last action was a FinishAction (proper completion) + * 2. The generated git patch is non-empty (actual changes were made) + */ + 'AgentFinishedCritic-Input': { + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__agent_finished__AgentFinishedCritic-Input__1'; + }; + /** + * AgentFinishedCritic + * @description Critic that evaluates whether an agent properly finished a task. + * + * This critic checks two main criteria: + * 1. The agent's last action was a FinishAction (proper completion) + * 2. The generated git patch is non-empty (actual changes were made) + */ + 'AgentFinishedCritic-Output': { + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__agent_finished__AgentFinishedCritic-Output__1'; + }; + /** + * AgentResponseResult + * @description The agent's final response for a conversation. + * + * Contains the text of the last agent finish message or text response. + * Empty string if the agent has not produced a final response yet. + */ + AgentResponseResult: { + /** + * Response + * @description The agent's final response text. Extracted from either a FinishAction message or the last agent MessageEvent. Empty string if no final response is available. + */ + response: string; + }; + /** AlwaysConfirm */ + 'AlwaysConfirm-Input': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__confirmation_policy__AlwaysConfirm-Input__1'; + }; + /** AlwaysConfirm */ + 'AlwaysConfirm-Output': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__confirmation_policy__AlwaysConfirm-Output__1'; + }; + /** + * AskAgentRequest + * @description Payload to ask the agent a simple question. + */ + AskAgentRequest: { + /** + * Question + * @description The question to ask the agent + */ + question: string; + }; + /** + * AskAgentResponse + * @description Response containing the agent's answer. + */ + AskAgentResponse: { + /** + * Response + * @description The agent's response to the question + */ + response: string; + }; + BaseWorkspace: + | components['schemas']['LocalWorkspace-Output'] + | components['schemas']['RemoteWorkspace']; + /** BashCommand */ + BashCommand: { + /** + * Command + * @description The bash command to execute + */ + command: string; + /** + * Cwd + * @description The current working directory + */ + cwd?: string | null; + /** + * Timeout + * @description The max number of seconds a command may be permitted to run. + * @default 300 + */ + timeout?: number; + /** Id */ + id?: string; + /** + * Timestamp + * Format: date-time + */ + timestamp?: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__agent_server__models__BashCommand-Output__1'; + }; + /** BashError */ + BashError: { + /** Id */ + id?: string; + /** + * Timestamp + * Format: date-time + */ + timestamp?: string; + /** + * Code + * @description Code for the error - typically an error type + */ + code: string; + /** + * Detail + * @description Details about the error + */ + detail: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__agent_server__models__BashError-Output__1'; + }; + BashEventBase: + | components['schemas']['BashCommand'] + | components['schemas']['BashError'] + | components['schemas']['BashOutput']; + /** BashEventPage */ + BashEventPage: { + /** Items */ + items: components['schemas']['BashEventBase'][]; + /** Next Page Id */ + next_page_id?: string | null; + }; + /** + * BashEventSortOrder + * @enum {string} + */ + BashEventSortOrder: 'TIMESTAMP' | 'TIMESTAMP_DESC'; + /** + * BashOutput + * @description Output of a bash command. A single command may have multiple pieces of output + * depending on how large the output is. + */ + BashOutput: { + /** Id */ + id?: string; + /** + * Timestamp + * Format: date-time + */ + timestamp?: string; + /** Command Id */ + command_id: string; + /** + * Order + * @description The order for this output, sequentially starting with 0 + * @default 0 + */ + order?: number; + /** + * Exit Code + * @description Exit code None implies the command is still running. + */ + exit_code?: number | null; + /** + * Stdout + * @description The standard output from the command + */ + stdout?: string | null; + /** + * Stderr + * @description The error output from the command + */ + stderr?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__agent_server__models__BashOutput-Output__1'; + }; + /** Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post */ + Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post: { + llm: components['schemas']['LLM-Input']; + }; + /** Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post */ + Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post: { + /** Profile Name */ + profile_name: string; + }; + /** Body_upload_file_query_api_file_upload_post */ + Body_upload_file_query_api_file_upload_post: { + /** + * File + * Format: binary + */ + file: string; + }; + /** + * BrowserAction + * @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. + */ + BrowserAction: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserAction-Output__1'; + }; + /** BrowserActionWithRisk */ + BrowserActionWithRisk: { + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserActionWithRisk-Output__1'; + }; + /** + * BrowserClickAction + * @description Schema for clicking elements. + */ + BrowserClickAction: { + /** + * Index + * @description The index of the element to click (from browser_get_state) + */ + index: number; + /** + * New Tab + * @description Whether to open any resulting navigation in a new tab. Default: False + * @default false + */ + new_tab?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserClickAction-Output__1'; + }; + /** BrowserClickActionWithRisk */ + BrowserClickActionWithRisk: { + /** + * Index + * @description The index of the element to click (from browser_get_state) + */ + index: number; + /** + * New Tab + * @description Whether to open any resulting navigation in a new tab. Default: False + * @default false + */ + new_tab?: boolean; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserClickActionWithRisk-Output__1'; + }; + /** + * BrowserClickTool + * @description Tool for clicking browser elements. + */ + BrowserClickTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserClickTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserCloseTabAction + * @description Schema for closing browser tabs. + */ + BrowserCloseTabAction: { + /** + * Tab Id + * @description 4 Character Tab ID of the tab to close (from browser_list_tabs) + */ + tab_id: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserCloseTabAction-Output__1'; + }; + /** BrowserCloseTabActionWithRisk */ + BrowserCloseTabActionWithRisk: { + /** + * Tab Id + * @description 4 Character Tab ID of the tab to close (from browser_list_tabs) + */ + tab_id: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserCloseTabActionWithRisk-Output__1'; + }; + /** + * BrowserCloseTabTool + * @description Tool for closing browser tabs. + */ + BrowserCloseTabTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserCloseTabTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserGetContentAction + * @description Schema for getting page content in markdown. + */ + BrowserGetContentAction: { + /** + * Extract Links + * @description Whether to include links in the content (default: False) + * @default false + */ + extract_links?: boolean; + /** + * Start From Char + * @description Character index to start from in the page content (default: 0) + * @default 0 + */ + start_from_char?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGetContentAction-Output__1'; + }; + /** BrowserGetContentActionWithRisk */ + BrowserGetContentActionWithRisk: { + /** + * Extract Links + * @description Whether to include links in the content (default: False) + * @default false + */ + extract_links?: boolean; + /** + * Start From Char + * @description Character index to start from in the page content (default: 0) + * @default 0 + */ + start_from_char?: number; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserGetContentActionWithRisk-Output__1'; + }; + /** + * BrowserGetContentTool + * @description Tool for getting page content in markdown. + */ + BrowserGetContentTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGetContentTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserGetStateAction + * @description Schema for getting browser state. + */ + BrowserGetStateAction: { + /** + * Include Screenshot + * @description Whether to include a screenshot of the current page. Default: False + * @default false + */ + include_screenshot?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGetStateAction-Output__1'; + }; + /** BrowserGetStateActionWithRisk */ + BrowserGetStateActionWithRisk: { + /** + * Include Screenshot + * @description Whether to include a screenshot of the current page. Default: False + * @default false + */ + include_screenshot?: boolean; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserGetStateActionWithRisk-Output__1'; + }; + /** + * BrowserGetStateTool + * @description Tool for getting browser state. + */ + BrowserGetStateTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGetStateTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserGetStorageAction + * @description Schema for getting browser storage (cookies, local storage, session storage). + */ + BrowserGetStorageAction: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGetStorageAction-Output__1'; + }; + /** BrowserGetStorageActionWithRisk */ + BrowserGetStorageActionWithRisk: { + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserGetStorageActionWithRisk-Output__1'; + }; + /** + * BrowserGetStorageTool + * @description Tool for getting browser storage. + */ + BrowserGetStorageTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGetStorageTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserGoBackAction + * @description Schema for going back in browser history. + */ + BrowserGoBackAction: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGoBackAction-Output__1'; + }; + /** BrowserGoBackActionWithRisk */ + BrowserGoBackActionWithRisk: { + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserGoBackActionWithRisk-Output__1'; + }; + /** + * BrowserGoBackTool + * @description Tool for going back in browser history. + */ + BrowserGoBackTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserGoBackTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserListTabsAction + * @description Schema for listing browser tabs. + */ + BrowserListTabsAction: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserListTabsAction-Output__1'; + }; + /** BrowserListTabsActionWithRisk */ + BrowserListTabsActionWithRisk: { + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserListTabsActionWithRisk-Output__1'; + }; + /** + * BrowserListTabsTool + * @description Tool for listing browser tabs. + */ + BrowserListTabsTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserListTabsTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserNavigateAction + * @description Schema for browser navigation. + */ + BrowserNavigateAction: { + /** + * Url + * @description The URL to navigate to + */ + url: string; + /** + * New Tab + * @description Whether to open in a new tab. Default: False + * @default false + */ + new_tab?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserNavigateAction-Output__1'; + }; + /** BrowserNavigateActionWithRisk */ + BrowserNavigateActionWithRisk: { + /** + * Url + * @description The URL to navigate to + */ + url: string; + /** + * New Tab + * @description Whether to open in a new tab. Default: False + * @default false + */ + new_tab?: boolean; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserNavigateActionWithRisk-Output__1'; + }; + /** + * BrowserNavigateTool + * @description Tool for browser navigation. + */ + BrowserNavigateTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserNavigateTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserObservation + * @description Base observation for browser operations. + */ + BrowserObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Screenshot Data + * @description Base64 screenshot data if available + */ + screenshot_data?: string | null; + /** + * Full Output Save Dir + * @description Directory where full output files are saved + */ + full_output_save_dir?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserObservation-Output__1'; + }; + /** + * BrowserScrollAction + * @description Schema for scrolling the page. + */ + BrowserScrollAction: { + /** + * Direction + * @description Direction to scroll. Options: 'up', 'down'. Default: 'down' + * @default down + * @enum {string} + */ + direction?: 'up' | 'down'; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserScrollAction-Output__1'; + }; + /** BrowserScrollActionWithRisk */ + BrowserScrollActionWithRisk: { + /** + * Direction + * @description Direction to scroll. Options: 'up', 'down'. Default: 'down' + * @default down + * @enum {string} + */ + direction?: 'up' | 'down'; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserScrollActionWithRisk-Output__1'; + }; + /** + * BrowserScrollTool + * @description Tool for scrolling the browser page. + */ + BrowserScrollTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserScrollTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserSetStorageAction + * @description Schema for setting browser storage (cookies, local storage, session storage). + */ + BrowserSetStorageAction: { + /** + * Storage State + * @description Storage state dictionary containing 'cookies' and 'origins' (from browser_get_storage) + */ + storage_state: { + [key: string]: unknown; + }; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserSetStorageAction-Output__1'; + }; + /** BrowserSetStorageActionWithRisk */ + BrowserSetStorageActionWithRisk: { + /** + * Storage State + * @description Storage state dictionary containing 'cookies' and 'origins' (from browser_get_storage) + */ + storage_state: { + [key: string]: unknown; + }; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserSetStorageActionWithRisk-Output__1'; + }; + /** + * BrowserSetStorageTool + * @description Tool for setting browser storage. + */ + BrowserSetStorageTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserSetStorageTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserStartRecordingAction + * @description Schema for starting browser session recording. + */ + BrowserStartRecordingAction: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserStartRecordingAction-Output__1'; + }; + /** BrowserStartRecordingActionWithRisk */ + BrowserStartRecordingActionWithRisk: { + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserStartRecordingActionWithRisk-Output__1'; + }; + /** + * BrowserStartRecordingTool + * @description Tool for starting browser session recording. + */ + BrowserStartRecordingTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserStartRecordingTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserStopRecordingAction + * @description Schema for stopping browser session recording. + */ + BrowserStopRecordingAction: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserStopRecordingAction-Output__1'; + }; + /** BrowserStopRecordingActionWithRisk */ + BrowserStopRecordingActionWithRisk: { + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserStopRecordingActionWithRisk-Output__1'; + }; + /** + * BrowserStopRecordingTool + * @description Tool for stopping browser session recording. + */ + BrowserStopRecordingTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserStopRecordingTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserSwitchTabAction + * @description Schema for switching browser tabs. + */ + BrowserSwitchTabAction: { + /** + * Tab Id + * @description 4 Character Tab ID of the tab to switch to (from browser_list_tabs) + */ + tab_id: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserSwitchTabAction-Output__1'; + }; + /** BrowserSwitchTabActionWithRisk */ + BrowserSwitchTabActionWithRisk: { + /** + * Tab Id + * @description 4 Character Tab ID of the tab to switch to (from browser_list_tabs) + */ + tab_id: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserSwitchTabActionWithRisk-Output__1'; + }; + /** + * BrowserSwitchTabTool + * @description Tool for switching browser tabs. + */ + BrowserSwitchTabTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserSwitchTabTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * 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. + */ + BrowserToolSet: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserToolSet-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * BrowserTypeAction + * @description Schema for typing text into elements. + */ + BrowserTypeAction: { + /** + * Index + * @description The index of the input element (from browser_get_state) + */ + index: number; + /** + * Text + * @description The text to type + */ + text: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserTypeAction-Output__1'; + }; + /** BrowserTypeActionWithRisk */ + BrowserTypeActionWithRisk: { + /** + * Index + * @description The index of the input element (from browser_get_state) + */ + index: number; + /** + * Text + * @description The text to type + */ + text: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__BrowserTypeActionWithRisk-Output__1'; + }; + /** + * BrowserTypeTool + * @description Tool for typing text into browser elements. + */ + BrowserTypeTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__browser_use__definition__BrowserTypeTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * CloudProxyRequest + * @description Envelope describing the upstream request to forward. + */ + CloudProxyRequest: { + /** + * Host + * @description Cloud host base URL, e.g. 'https://app.all-hands.dev'. Must match the configured allowlist. + */ + host: string; + /** + * Method + * @default GET + */ + method?: string; + /** + * Path + * @description Path on the cloud host, e.g. '/api/organizations' + */ + path: string; + /** + * Headers + * @description Headers to forward, including the Authorization bearer token for the cloud backend. + */ + headers?: { + [key: string]: string; + }; + /** Body */ + body?: unknown; + /** + * Timeout Seconds + * @default 15 + */ + timeout_seconds?: number; + }; + /** + * CmdOutputMetadata + * @description Additional metadata captured from PS1 + */ + CmdOutputMetadata: { + /** + * Exit Code + * @description The exit code of the last executed command. + * @default -1 + */ + exit_code?: number; + /** + * Pid + * @description The process ID of the last executed command. + * @default -1 + */ + pid?: number; + /** + * Username + * @description The username of the current user. + */ + username?: string | null; + /** + * Hostname + * @description The hostname of the machine. + */ + hostname?: string | null; + /** + * Working Dir + * @description The current working directory. + */ + working_dir?: string | null; + /** + * Py Interpreter Path + * @description The path to the current Python interpreter, if any. + */ + py_interpreter_path?: string | null; + /** + * Prefix + * @description Prefix to add to command output + * @default + */ + prefix?: string; + /** + * Suffix + * @description Suffix to add to command output + * @default + */ + suffix?: string; + }; + /** + * Condensation + * @description This action indicates a condensation of the conversation history is happening. + */ + Condensation: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Forgotten Event Ids + * @description The IDs of the events that are being forgotten (removed from the `View` given to the LLM). + */ + forgotten_event_ids?: string[]; + /** + * Summary + * @description An optional summary of the events being forgotten. + */ + summary?: string | null; + /** + * Summary Offset + * @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. + */ + summary_offset?: number | null; + /** + * Llm Response Id + * @description Completion or Response ID of the LLM response that generated this event + */ + llm_response_id: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__condenser__Condensation-Output__1'; + }; + /** + * CondensationRequest + * @description This action is used to request a condensation of the conversation history. + * + * Attributes: + * action (str): The action type, namely ActionType.CONDENSATION_REQUEST. + */ + CondensationRequest: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__condenser__CondensationRequest-Output__1'; + }; + /** + * CondensationSummaryEvent + * @description This event represents a summary generated by a condenser. + */ + CondensationSummaryEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** Summary */ + summary: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__condenser__CondensationSummaryEvent-Output__1'; + }; + 'CondenserBase-Input': + | components['schemas']['LLMSummarizingCondenser-Input'] + | components['schemas']['NoOpCondenser-Input'] + | components['schemas']['PipelineCondenser-Input']; + 'CondenserBase-Output': + | components['schemas']['LLMSummarizingCondenser-Output'] + | components['schemas']['NoOpCondenser-Output'] + | components['schemas']['PipelineCondenser-Output']; + /** ConfirmRisky */ + 'ConfirmRisky-Input': { + /** @default HIGH */ + threshold?: components['schemas']['SecurityRisk']; + /** + * Confirm Unknown + * @default true + */ + confirm_unknown?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__confirmation_policy__ConfirmRisky-Input__1'; + }; + /** ConfirmRisky */ + 'ConfirmRisky-Output': { + /** @default HIGH */ + threshold?: components['schemas']['SecurityRisk']; + /** + * Confirm Unknown + * @default true + */ + confirm_unknown?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__confirmation_policy__ConfirmRisky-Output__1'; + }; + 'ConfirmationPolicyBase-Input': + | components['schemas']['AlwaysConfirm-Input'] + | components['schemas']['ConfirmRisky-Input'] + | components['schemas']['NeverConfirm-Input']; + 'ConfirmationPolicyBase-Output': + | components['schemas']['AlwaysConfirm-Output'] + | components['schemas']['ConfirmRisky-Output'] + | components['schemas']['NeverConfirm-Output']; + /** + * ConfirmationResponseRequest + * @description Payload to accept or reject a pending action. + */ + ConfirmationResponseRequest: { + /** Accept */ + accept: boolean; + /** + * Reason + * @default User rejected the action. + */ + reason?: string; + }; + /** + * ConversationErrorEvent + * @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. + */ + ConversationErrorEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @description The source of this event + * @enum {string} + */ + source: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Code + * @description Code for the error - typically a type + */ + code: string; + /** + * Detail + * @description Details about the error + */ + detail: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__conversation_error__ConversationErrorEvent-Output__1'; + }; + /** + * ConversationExecutionStatus + * @description Enum representing the current execution state of the conversation. + * @enum {string} + */ + ConversationExecutionStatus: + | 'idle' + | 'running' + | 'paused' + | 'waiting_for_confirmation' + | 'finished' + | 'error' + | 'stuck' + | 'deleting'; + /** + * ConversationInfo + * @description Information about a conversation running locally without a Runtime sandbox. + */ + ConversationInfo: { + /** + * Id + * Format: uuid + * @description Unique conversation ID + */ + id: string; + /** @description Workspace used by the agent to execute commands and read/write files. Not the process working directory. */ + workspace: components['schemas']['BaseWorkspace']; + /** + * Persistence Dir + * @description Directory for persisting conversation state and events. If None, conversation will not be persisted. + * @default workspace/conversations + */ + persistence_dir?: string | null; + /** + * Max Iterations + * @description Maximum number of iterations the agent can perform in a single run. + * @default 500 + */ + max_iterations?: number; + /** + * Stuck Detection + * @description Whether to enable stuck detection for the agent. + * @default true + */ + stuck_detection?: boolean; + /** @default idle */ + execution_status?: components['schemas']['ConversationExecutionStatus']; + /** + * @default { + * "kind": "NeverConfirm" + * } + */ + confirmation_policy?: components['schemas']['ConfirmationPolicyBase-Output']; + /** @description Optional security analyzer to evaluate action risks. */ + security_analyzer?: components['schemas']['SecurityAnalyzerBase-Output'] | null; + /** + * Activated Knowledge Skills + * @description List of activated knowledge skills name + */ + activated_knowledge_skills?: string[]; + /** + * Invoked Skills + * @description Names of progressive-disclosure skills explicitly invoked via the `invoke_skill` tool. + */ + invoked_skills?: string[]; + /** + * Blocked Actions + * @description Actions blocked by PreToolUse hooks, keyed by action ID + */ + blocked_actions?: { + [key: string]: string; + }; + /** + * Blocked Messages + * @description Messages blocked by UserPromptSubmit hooks, keyed by message ID + */ + blocked_messages?: { + [key: string]: string; + }; + /** + * Last User Message Id + * @description Most recent user MessageEvent id for hook block checks. Updated when user messages are emitted so Agent.step can pop blocked_messages without scanning the event log. If None, hook-blocked checks are skipped (legacy conversations). + */ + last_user_message_id?: string | null; + /** @description Conversation statistics for tracking LLM metrics */ + stats?: components['schemas']['ConversationStats']; + /** @description Registry for handling secrets and sensitive data */ + secret_registry?: components['schemas']['SecretRegistry']; + /** + * Agent State + * @description Dictionary for agent-specific runtime state that persists across iterations. + */ + agent_state?: { + [key: string]: unknown; + }; + /** @description Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks. */ + hook_config?: components['schemas']['HookConfig-Output'] | null; + /** + * Title + * @description User-defined title for the conversation + */ + title?: string | null; + metrics?: components['schemas']['MetricsSnapshot'] | null; + /** + * Created At + * Format: date-time + */ + created_at?: string; + /** + * Updated At + * Format: date-time + */ + updated_at?: string; + /** + * Tags + * @description Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. + */ + tags?: { + [key: string]: string; + }; + /** @description The agent running in the conversation. */ + agent: components['schemas']['AgentBase-Output']; + }; + /** ConversationPage */ + ConversationPage: { + /** Items */ + items: components['schemas']['ConversationInfo'][]; + /** Next Page Id */ + next_page_id?: string | null; + }; + /** + * ConversationSortOrder + * @description Enum for conversation sorting options. + * @enum {string} + */ + ConversationSortOrder: 'CREATED_AT' | 'UPDATED_AT' | 'CREATED_AT_DESC' | 'UPDATED_AT_DESC'; + /** + * ConversationStateUpdateEvent + * @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. + */ + ConversationStateUpdateEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Key + * @description Unique key for this state update event + */ + key?: string; + /** + * Value + * @description Serialized conversation state updates + */ + value?: unknown; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__conversation_state__ConversationStateUpdateEvent-Output__1'; + }; + ConversationStats: { + [key: string]: unknown; + }; + /** Cost */ + Cost: { + /** Model */ + model: string; + /** + * Cost + * @description Cost must be non-negative + */ + cost: number; + /** Timestamp */ + timestamp?: number; + }; + 'CriticBase-Input': + | components['schemas']['AgentFinishedCritic-Input'] + | components['schemas']['APIBasedCritic-Input'] + | components['schemas']['EmptyPatchCritic-Input'] + | components['schemas']['PassCritic-Input']; + 'CriticBase-Output': + | components['schemas']['AgentFinishedCritic-Output'] + | components['schemas']['APIBasedCritic-Output'] + | components['schemas']['EmptyPatchCritic-Output'] + | components['schemas']['PassCritic-Output']; + /** + * CriticResult + * @description A critic result is a score and a message. + */ + CriticResult: { + /** + * Score + * @description A predicted probability of success between 0 and 1. + */ + score: number; + /** + * Message + * @description An optional message explaining the score. + */ + message: string | null; + /** + * Metadata + * @description Optional metadata about the critic evaluation. Can include event_ids and categorized_features for visualization. + */ + metadata?: { + [key: string]: unknown; + } | null; + }; + /** + * DelegateAction + * @description Schema for delegation operations. + */ + DelegateAction: { + /** + * Command + * @description The commands to run. Allowed options are: `spawn`, `delegate`. + * @enum {string} + */ + command: 'spawn' | 'delegate'; + /** + * Ids + * @description Required parameter of `spawn` command. List of identifiers to initialize sub-agents with. + */ + ids?: string[] | null; + /** + * Agent Types + * @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. + */ + agent_types?: string[] | null; + /** + * Tasks + * @description Required parameter of `delegate` command. Dictionary mapping sub-agent identifiers to task descriptions. + */ + tasks?: { + [key: string]: string; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__delegate__definition__DelegateAction-Output__1'; + }; + /** DelegateActionWithRisk */ + DelegateActionWithRisk: { + /** + * Command + * @description The commands to run. Allowed options are: `spawn`, `delegate`. + * @enum {string} + */ + command: 'spawn' | 'delegate'; + /** + * Ids + * @description Required parameter of `spawn` command. List of identifiers to initialize sub-agents with. + */ + ids?: string[] | null; + /** + * Agent Types + * @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. + */ + agent_types?: string[] | null; + /** + * Tasks + * @description Required parameter of `delegate` command. Dictionary mapping sub-agent identifiers to task descriptions. + */ + tasks?: { + [key: string]: string; + } | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__DelegateActionWithRisk-Output__1'; + }; + /** + * DelegateObservation + * @description Observation from delegation operations. + */ + DelegateObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Command + * @description The command that was executed + * @enum {string} + */ + command: 'spawn' | 'delegate'; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__delegate__definition__DelegateObservation-Output__1'; + }; + /** + * DelegateTool + * @description A ToolDefinition subclass that automatically initializes a DelegateExecutor. + * + * .. deprecated:: 1.16.0 + * DelegateTool is deprecated in favor of TaskToolSet. Use TaskToolSet for + * sub-agent delegation. DelegateTool will be removed in version 1.23.0. + */ + DelegateTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__delegate__definition__DelegateTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * DesktopUrlResponse + * @description Response model for Desktop URL. + */ + DesktopUrlResponse: { + /** Url */ + url: string | null; + }; + /** + * EditAction + * @description Schema for edit operation. + */ + EditAction: { + /** + * File Path + * @description The path to the file to modify. + */ + file_path: 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. + */ + old_string: string; + /** + * New String + * @description The text to replace it with. + */ + new_string: string; + /** + * Expected Replacements + * @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. + * @default 1 + */ + expected_replacements?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__edit__definition__EditAction-Output__1'; + }; + /** EditActionWithRisk */ + EditActionWithRisk: { + /** + * File Path + * @description The path to the file to modify. + */ + file_path: 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. + */ + old_string: string; + /** + * New String + * @description The text to replace it with. + */ + new_string: string; + /** + * Expected Replacements + * @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. + * @default 1 + */ + expected_replacements?: number; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__EditActionWithRisk-Output__1'; + }; + /** + * EditObservation + * @description Observation from editing a file. + */ + EditObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * File Path + * @description The file path that was edited. + */ + file_path?: string | null; + /** + * Is New File + * @description Whether a new file was created. + * @default false + */ + is_new_file?: boolean; + /** + * Replacements Made + * @description Number of replacements actually made. + * @default 0 + */ + replacements_made?: number; + /** + * Old Content + * @description The content before the edit. + */ + old_content?: string | null; + /** + * New Content + * @description The content after the edit. + */ + new_content?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__edit__definition__EditObservation-Output__1'; + }; + /** + * EditTool + * @description Tool for editing files via find/replace. + */ + EditTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__edit__definition__EditTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * EmptyPatchCritic + * @description Critic that only evaluates whether a git patch is non-empty. + * + * This critic checks only one criterion: + * - The generated git patch is non-empty (actual changes were made) + * + * Unlike AgentFinishedCritic, this critic does not check for proper + * agent completion with FinishAction. + */ + 'EmptyPatchCritic-Input': { + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__empty_patch__EmptyPatchCritic-Input__1'; + }; + /** + * EmptyPatchCritic + * @description Critic that only evaluates whether a git patch is non-empty. + * + * This critic checks only one criterion: + * - The generated git patch is non-empty (actual changes were made) + * + * Unlike AgentFinishedCritic, this critic does not check for proper + * agent completion with FinishAction. + */ + 'EmptyPatchCritic-Output': { + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__empty_patch__EmptyPatchCritic-Output__1'; + }; + /** + * EnsembleSecurityAnalyzer + * @description Wire multiple analyzers together and take the worst-case risk. + * + * Use this as the top-level analyzer you set on a conversation. It + * calls each child analyzer, collects their risk assessments, and + * returns the highest concrete risk. It does not perform any detection, + * extraction, or normalization of its own. + * + * How UNKNOWN works (default, ``propagate_unknown=False``): if *all* + * children return UNKNOWN, the ensemble returns UNKNOWN (which + * ``ConfirmRisky`` confirms by default). If any child returns a + * concrete level, UNKNOWN results are filtered out and the highest + * concrete level wins. + * + * With ``propagate_unknown=True``: if *any* child returns UNKNOWN, the + * ensemble returns UNKNOWN regardless of other results. Use this in + * stricter environments where incomplete assessment should trigger + * confirmation. + * + * If a child analyzer raises an exception, it contributes HIGH + * (fail-closed, logged). This prevents a broken analyzer from silently + * degrading safety. + * + * Example:: + * + * from openhands.sdk.security import ( + * EnsembleSecurityAnalyzer, + * PatternSecurityAnalyzer, + * PolicyRailSecurityAnalyzer, + * ConfirmRisky, + * SecurityRisk, + * ) + * + * analyzer = EnsembleSecurityAnalyzer( + * analyzers=[ + * PolicyRailSecurityAnalyzer(), + * PatternSecurityAnalyzer(), + * ] + * ) + * policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM) + */ + 'EnsembleSecurityAnalyzer-Input': { + /** + * Analyzers + * @description Analyzers whose assessments are combined via max-severity + */ + analyzers: components['schemas']['SecurityAnalyzerBase-Input'][]; + /** + * Propagate Unknown + * @description When True, any child returning UNKNOWN causes the ensemble to return UNKNOWN. When False (default), UNKNOWN is filtered out if any child returns a concrete level. + * @default false + */ + propagate_unknown?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__ensemble__EnsembleSecurityAnalyzer-Input__1'; + }; + /** + * EnsembleSecurityAnalyzer + * @description Wire multiple analyzers together and take the worst-case risk. + * + * Use this as the top-level analyzer you set on a conversation. It + * calls each child analyzer, collects their risk assessments, and + * returns the highest concrete risk. It does not perform any detection, + * extraction, or normalization of its own. + * + * How UNKNOWN works (default, ``propagate_unknown=False``): if *all* + * children return UNKNOWN, the ensemble returns UNKNOWN (which + * ``ConfirmRisky`` confirms by default). If any child returns a + * concrete level, UNKNOWN results are filtered out and the highest + * concrete level wins. + * + * With ``propagate_unknown=True``: if *any* child returns UNKNOWN, the + * ensemble returns UNKNOWN regardless of other results. Use this in + * stricter environments where incomplete assessment should trigger + * confirmation. + * + * If a child analyzer raises an exception, it contributes HIGH + * (fail-closed, logged). This prevents a broken analyzer from silently + * degrading safety. + * + * Example:: + * + * from openhands.sdk.security import ( + * EnsembleSecurityAnalyzer, + * PatternSecurityAnalyzer, + * PolicyRailSecurityAnalyzer, + * ConfirmRisky, + * SecurityRisk, + * ) + * + * analyzer = EnsembleSecurityAnalyzer( + * analyzers=[ + * PolicyRailSecurityAnalyzer(), + * PatternSecurityAnalyzer(), + * ] + * ) + * policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM) + */ + 'EnsembleSecurityAnalyzer-Output': { + /** + * Analyzers + * @description Analyzers whose assessments are combined via max-severity + */ + analyzers: components['schemas']['SecurityAnalyzerBase-Output'][]; + /** + * Propagate Unknown + * @description When True, any child returning UNKNOWN causes the ensemble to return UNKNOWN. When False (default), UNKNOWN is filtered out if any child returns a concrete level. + * @default false + */ + propagate_unknown?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__ensemble__EnsembleSecurityAnalyzer-Output__1'; + }; + Event: + | components['schemas']['ServerErrorEvent'] + | components['schemas']['ACPToolCallEvent'] + | components['schemas']['Condensation'] + | components['schemas']['CondensationRequest'] + | components['schemas']['CondensationSummaryEvent'] + | components['schemas']['ConversationErrorEvent'] + | components['schemas']['ConversationStateUpdateEvent'] + | components['schemas']['HookExecutionEvent'] + | components['schemas']['LLMCompletionLogEvent'] + | components['schemas']['ActionEvent'] + | components['schemas']['MessageEvent'] + | components['schemas']['AgentErrorEvent'] + | components['schemas']['ObservationEvent'] + | components['schemas']['UserRejectObservation'] + | components['schemas']['SystemPromptEvent'] + | components['schemas']['StreamingDeltaEvent'] + | components['schemas']['TokenEvent'] + | components['schemas']['PauseEvent']; + /** EventPage */ + EventPage: { + /** Items */ + items: components['schemas']['Event'][]; + /** Next Page Id */ + next_page_id?: string | null; + }; + /** + * EventSortOrder + * @description Enum for event sorting options. + * @enum {string} + */ + EventSortOrder: 'TIMESTAMP' | 'TIMESTAMP_DESC'; + /** ExecuteBashRequest */ + ExecuteBashRequest: { + /** + * Command + * @description The bash command to execute + */ + command: string; + /** + * Cwd + * @description The current working directory + */ + cwd?: string | null; + /** + * Timeout + * @description The max number of seconds a command may be permitted to run. + * @default 300 + */ + timeout?: number; + }; + /** + * ExposedUrl + * @description Represents an exposed URL from the sandbox. + */ + ExposedUrl: { + /** Name */ + name: string; + /** Url */ + url: string; + /** Port */ + port: number; + }; + /** + * FallbackStrategy + * @description Encapsulates fallback behavior for LLM calls. + * + * When the primary LLM fails with a transient error (after retries), + * this strategy tries alternate LLMs loaded from LLMProfileStore profiles. + * Fallback is per-call: each new request starts with the primary model. + */ + FallbackStrategy: { + /** + * Fallback Llms + * @description Ordered list of LLM profile names to try on transient failure. + */ + fallback_llms: string[]; + /** + * Profile Store Dir + * @description Path to directory containing profiles. If not specified, defaults to `.openhands/profiles`. + */ + profile_store_dir?: string | null; + }; + /** FileBrowserEntry */ + FileBrowserEntry: { + /** Label */ + label: string; + /** Path */ + path: string; + }; + /** + * FileEditorAction + * @description Schema for file editor operations. + */ + FileEditorAction: { + /** + * Command + * @description The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`. + * @enum {string} + */ + command: 'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'; + /** + * Path + * @description Absolute path to file or directory. + */ + path: string; + /** + * File Text + * @description Required parameter of `create` command, with the content of the file to be created. + */ + file_text?: string | null; + /** + * Old Str + * @description Required parameter of `str_replace` command containing the string in `path` to replace. + */ + old_str?: string | null; + /** + * New Str + * @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. + */ + new_str?: string | null; + /** + * Insert Line + * @description Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. + */ + insert_line?: number | null; + /** + * View Range + * @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. + */ + view_range?: number[] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__file_editor__definition__FileEditorAction-Output__1'; + }; + /** FileEditorActionWithRisk */ + FileEditorActionWithRisk: { + /** + * Command + * @description The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`. + * @enum {string} + */ + command: 'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'; + /** + * Path + * @description Absolute path to file or directory. + */ + path: string; + /** + * File Text + * @description Required parameter of `create` command, with the content of the file to be created. + */ + file_text?: string | null; + /** + * Old Str + * @description Required parameter of `str_replace` command containing the string in `path` to replace. + */ + old_str?: string | null; + /** + * New Str + * @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. + */ + new_str?: string | null; + /** + * Insert Line + * @description Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. + */ + insert_line?: number | null; + /** + * View Range + * @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. + */ + view_range?: number[] | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__FileEditorActionWithRisk-Output__1'; + }; + /** + * FileEditorObservation + * @description A ToolResult that can be rendered as a CLI output. + */ + FileEditorObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Command + * @description The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`. + * @enum {string} + */ + command: 'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'; + /** + * Path + * @description The file path that was edited. + */ + path?: string | null; + /** + * Prev Exist + * @description Indicates if the file previously existed. If not, it was created. + * @default true + */ + prev_exist?: boolean; + /** + * Old Content + * @description The content of the file before the edit. + */ + old_content?: string | null; + /** + * New Content + * @description The content of the file after the edit. + */ + new_content?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__file_editor__definition__FileEditorObservation-Output__1'; + }; + /** + * FileEditorTool + * @description A ToolDefinition subclass that automatically initializes a FileEditorExecutor. + */ + FileEditorTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__file_editor__definition__FileEditorTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * FileEntry + * @description Information about a file or directory. + */ + FileEntry: { + /** + * Name + * @description Name of the file or directory + */ + name: string; + /** + * Path + * @description Absolute path to the file or directory + */ + path: string; + /** + * Is Directory + * @description Whether this entry is a directory + */ + is_directory: boolean; + /** + * Size + * @description Size of the file in bytes (0 for directories) + */ + size: number; + /** + * Modified Time + * Format: date-time + * @description Last modified timestamp + */ + modified_time: string; + }; + /** FinishAction */ + FinishAction: { + /** + * Message + * @description Final message to send to the user. + */ + message: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__finish__FinishAction-Output__1'; + }; + /** FinishActionWithRisk */ + FinishActionWithRisk: { + /** + * Message + * @description Final message to send to the user. + */ + message: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__FinishActionWithRisk-Output__1'; + }; + /** + * FinishObservation + * @description Observation returned after finishing a task. + * The FinishAction itself contains the message sent to the user so no + * extra fields are needed here. + */ + FinishObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__finish__FinishObservation-Output__1'; + }; + /** + * FinishTool + * @description Tool for signaling the completion of a task or conversation. + */ + FinishTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__finish__FinishTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * ForkConversationRequest + * @description Payload to fork a conversation. + */ + ForkConversationRequest: { + /** + * Id + * @description ID for the forked conversation (auto-generated if null) + */ + id?: string | null; + /** + * Title + * @description Optional title for the forked conversation + */ + title?: string | null; + /** + * Tags + * @description Optional tags for the forked conversation. Keys must be lowercase alphanumeric. + */ + tags?: { + [key: string]: string; + } | null; + /** + * Reset Metrics + * @description If true, cost/token stats start fresh on the fork. If false, metrics are copied from the source. + * @default true + */ + reset_metrics?: boolean; + }; + /** GitChange */ + GitChange: { + status: components['schemas']['GitChangeStatus']; + /** + * Path + * Format: path + */ + path: string; + }; + /** + * GitChangeStatus + * @enum {string} + */ + GitChangeStatus: 'MOVED' | 'ADDED' | 'DELETED' | 'UPDATED'; + /** GitDiff */ + GitDiff: { + /** Modified */ + modified: string | null; + /** Original */ + original: string | null; + }; + /** + * GlobAction + * @description Schema for glob pattern matching operations. + */ + GlobAction: { + /** + * Pattern + * @description The glob pattern to match files (e.g., "**\/*.js", "src/**\/*.ts") + */ + pattern: string; + /** + * Path + * @description The directory (absolute path) to search in. Defaults to the current working directory. + */ + path?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__glob__definition__GlobAction-Output__1'; + }; + /** GlobActionWithRisk */ + GlobActionWithRisk: { + /** + * Pattern + * @description The glob pattern to match files (e.g., "**\/*.js", "src/**\/*.ts") + */ + pattern: string; + /** + * Path + * @description The directory (absolute path) to search in. Defaults to the current working directory. + */ + path?: string | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__GlobActionWithRisk-Output__1'; + }; + /** + * GlobObservation + * @description Observation from glob pattern matching operations. + */ + GlobObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Files + * @description List of matching file paths sorted by modification time + */ + files: string[]; + /** + * Pattern + * @description The glob pattern that was used + */ + pattern: string; + /** + * Search Path + * @description The directory that was searched + */ + search_path: string; + /** + * Truncated + * @description Whether results were truncated to 100 files + * @default false + */ + truncated?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__glob__definition__GlobObservation-Output__1'; + }; + /** + * GlobTool + * @description A ToolDefinition subclass that automatically initializes a GlobExecutor. + */ + GlobTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__glob__definition__GlobTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * GraySwanAnalyzer + * @description Security analyzer using GraySwan's Cygnal API for AI safety monitoring. + * + * This analyzer sends conversation history and pending actions to the GraySwan + * Cygnal API for security analysis. The API returns a violation score which is + * mapped to SecurityRisk levels. + * + * Environment Variables: + * GRAYSWAN_API_KEY: Required API key for GraySwan authentication + * GRAYSWAN_POLICY_ID: Optional policy ID for custom GraySwan policy + * + * Example: + * >>> from openhands.sdk.security.grayswan import GraySwanAnalyzer + * >>> analyzer = GraySwanAnalyzer() + * >>> risk = analyzer.security_risk(action_event) + */ + 'GraySwanAnalyzer-Input': { + /** + * History Limit + * @description Number of recent events to include as context + * @default 20 + */ + history_limit?: number; + /** + * Max Message Chars + * @description Max characters for conversation processing + * @default 30000 + */ + max_message_chars?: number; + /** + * Timeout + * @description Request timeout in seconds + * @default 30 + */ + timeout?: number; + /** + * Low Threshold + * @description Risk threshold for LOW classification (score <= threshold) + * @default 0.3 + */ + low_threshold?: number; + /** + * Medium Threshold + * @description Risk threshold for MEDIUM classification (score <= threshold) + * @default 0.7 + */ + medium_threshold?: number; + /** + * Api Url + * @description GraySwan Cygnal API endpoint + * @default https://api.grayswan.ai/cygnal/monitor + */ + api_url?: string; + /** + * Api Key + * @description GraySwan API key (via GRAYSWAN_API_KEY env var) + */ + api_key?: string | null; + /** + * Policy Id + * @description GraySwan policy ID (via GRAYSWAN_POLICY_ID env var) + */ + policy_id?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__grayswan__analyzer__GraySwanAnalyzer-Input__1'; + }; + /** + * GraySwanAnalyzer + * @description Security analyzer using GraySwan's Cygnal API for AI safety monitoring. + * + * This analyzer sends conversation history and pending actions to the GraySwan + * Cygnal API for security analysis. The API returns a violation score which is + * mapped to SecurityRisk levels. + * + * Environment Variables: + * GRAYSWAN_API_KEY: Required API key for GraySwan authentication + * GRAYSWAN_POLICY_ID: Optional policy ID for custom GraySwan policy + * + * Example: + * >>> from openhands.sdk.security.grayswan import GraySwanAnalyzer + * >>> analyzer = GraySwanAnalyzer() + * >>> risk = analyzer.security_risk(action_event) + */ + 'GraySwanAnalyzer-Output': { + /** + * History Limit + * @description Number of recent events to include as context + * @default 20 + */ + history_limit?: number; + /** + * Max Message Chars + * @description Max characters for conversation processing + * @default 30000 + */ + max_message_chars?: number; + /** + * Timeout + * @description Request timeout in seconds + * @default 30 + */ + timeout?: number; + /** + * Low Threshold + * @description Risk threshold for LOW classification (score <= threshold) + * @default 0.3 + */ + low_threshold?: number; + /** + * Medium Threshold + * @description Risk threshold for MEDIUM classification (score <= threshold) + * @default 0.7 + */ + medium_threshold?: number; + /** + * Api Url + * @description GraySwan Cygnal API endpoint + * @default https://api.grayswan.ai/cygnal/monitor + */ + api_url?: string; + /** + * Api Key + * @description GraySwan API key (via GRAYSWAN_API_KEY env var) + */ + api_key?: string | null; + /** + * Policy Id + * @description GraySwan policy ID (via GRAYSWAN_POLICY_ID env var) + */ + policy_id?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__grayswan__analyzer__GraySwanAnalyzer-Output__1'; + }; + /** + * GrepAction + * @description Schema for grep content search operations. + */ + GrepAction: { + /** + * Pattern + * @description The regex pattern to search for in file contents + */ + pattern: string; + /** + * Path + * @description The directory (absolute path) to search in. Defaults to the current working directory. + */ + path?: string | null; + /** + * Include + * @description Optional file pattern to filter which files to search (e.g., "*.js", "*.{ts,tsx}") + */ + include?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__grep__definition__GrepAction-Output__1'; + }; + /** GrepActionWithRisk */ + GrepActionWithRisk: { + /** + * Pattern + * @description The regex pattern to search for in file contents + */ + pattern: string; + /** + * Path + * @description The directory (absolute path) to search in. Defaults to the current working directory. + */ + path?: string | null; + /** + * Include + * @description Optional file pattern to filter which files to search (e.g., "*.js", "*.{ts,tsx}") + */ + include?: string | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__GrepActionWithRisk-Output__1'; + }; + /** + * GrepObservation + * @description Observation from grep content search operations. + */ + GrepObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Matches + * @description List of file paths containing the pattern + */ + matches: string[]; + /** + * Pattern + * @description The regex pattern that was used + */ + pattern: string; + /** + * Search Path + * @description The directory that was searched + */ + search_path: string; + /** + * Include Pattern + * @description The file pattern filter that was used + */ + include_pattern?: string | null; + /** + * Truncated + * @description Whether results were truncated to 100 files + * @default false + */ + truncated?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__grep__definition__GrepObservation-Output__1'; + }; + /** + * GrepTool + * @description A ToolDefinition subclass that automatically initializes a GrepExecutor. + */ + GrepTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__grep__definition__GrepTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** HTTPValidationError */ + HTTPValidationError: { + /** Detail */ + detail?: components['schemas']['ValidationError'][]; + }; + /** HealthStatus */ + HealthStatus: { + /** Status */ + status: string; + }; + /** HomeResponse */ + HomeResponse: { + /** Home */ + home: string; + /** + * Favorites + * @default [] + */ + favorites?: components['schemas']['FileBrowserEntry'][]; + /** + * Locations + * @default [] + */ + locations?: components['schemas']['FileBrowserEntry'][]; + }; + /** + * HookConfig + * @description Configuration for all hooks. + * + * Hooks can be configured either by loading from `.openhands/hooks.json` or + * by directly instantiating with typed fields: + * + * # Direct instantiation with typed fields (recommended): + * config = HookConfig( + * pre_tool_use=[ + * HookMatcher( + * matcher="terminal", + * hooks=[HookDefinition(command="block_dangerous.sh")] + * ) + * ] + * ) + * + * # Load from JSON file: + * config = HookConfig.load(".openhands/hooks.json") + */ + 'HookConfig-Input': { + /** + * Pre Tool Use + * @description Hooks that run before tool execution + */ + pre_tool_use?: components['schemas']['HookMatcher-Input'][]; + /** + * Post Tool Use + * @description Hooks that run after tool execution + */ + post_tool_use?: components['schemas']['HookMatcher-Input'][]; + /** + * User Prompt Submit + * @description Hooks that run when user submits a prompt + */ + user_prompt_submit?: components['schemas']['HookMatcher-Input'][]; + /** + * Session Start + * @description Hooks that run when a session starts + */ + session_start?: components['schemas']['HookMatcher-Input'][]; + /** + * Session End + * @description Hooks that run when a session ends + */ + session_end?: components['schemas']['HookMatcher-Input'][]; + /** + * Stop + * @description Hooks that run when the agent attempts to stop + */ + stop?: components['schemas']['HookMatcher-Input'][]; + }; + /** + * HookConfig + * @description Configuration for all hooks. + * + * Hooks can be configured either by loading from `.openhands/hooks.json` or + * by directly instantiating with typed fields: + * + * # Direct instantiation with typed fields (recommended): + * config = HookConfig( + * pre_tool_use=[ + * HookMatcher( + * matcher="terminal", + * hooks=[HookDefinition(command="block_dangerous.sh")] + * ) + * ] + * ) + * + * # Load from JSON file: + * config = HookConfig.load(".openhands/hooks.json") + */ + 'HookConfig-Output': { + /** + * Pre Tool Use + * @description Hooks that run before tool execution + */ + pre_tool_use?: components['schemas']['HookMatcher-Output'][]; + /** + * Post Tool Use + * @description Hooks that run after tool execution + */ + post_tool_use?: components['schemas']['HookMatcher-Output'][]; + /** + * User Prompt Submit + * @description Hooks that run when user submits a prompt + */ + user_prompt_submit?: components['schemas']['HookMatcher-Output'][]; + /** + * Session Start + * @description Hooks that run when a session starts + */ + session_start?: components['schemas']['HookMatcher-Output'][]; + /** + * Session End + * @description Hooks that run when a session ends + */ + session_end?: components['schemas']['HookMatcher-Output'][]; + /** + * Stop + * @description Hooks that run when the agent attempts to stop + */ + stop?: components['schemas']['HookMatcher-Output'][]; + }; + /** + * HookDefinition + * @description A single hook definition. + */ + HookDefinition: { + /** @default command */ + type?: components['schemas']['HookType']; + /** Command */ + command: string; + /** Prompt */ + prompt?: string | null; + /** + * Timeout + * @default 60 + */ + timeout?: number; + /** + * Async + * @default false + */ + async?: boolean; + }; + /** + * HookExecutionEvent + * @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. + */ + HookExecutionEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @description Source is always 'hook' for hook execution events + * @default hook + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Hook Event Type + * @description The type of hook event that triggered this execution + * @enum {string} + */ + hook_event_type: + | 'PreToolUse' + | 'PostToolUse' + | 'UserPromptSubmit' + | 'SessionStart' + | 'SessionEnd' + | 'Stop'; + /** + * Hook Command + * @description The hook command that was executed + */ + hook_command: string; + /** + * Tool Name + * @description Tool name for PreToolUse/PostToolUse hooks + */ + tool_name?: string | null; + /** + * Success + * @description Whether the hook executed successfully + */ + success: boolean; + /** + * Blocked + * @description Whether the hook blocked the operation (exit code 2 or deny) + * @default false + */ + blocked?: boolean; + /** + * Exit Code + * @description Exit code from the hook command + */ + exit_code: number; + /** + * Stdout + * @description Standard output from the hook + * @default + */ + stdout?: string; + /** + * Stderr + * @description Standard error from the hook + * @default + */ + stderr?: string; + /** + * Reason + * @description Reason provided by hook (for blocking) + */ + reason?: string | null; + /** + * Additional Context + * @description Additional context injected by hook (e.g., for UserPromptSubmit) + */ + additional_context?: string | null; + /** + * Error + * @description Error message if hook execution failed + */ + error?: string | null; + /** + * Action Id + * @description ID of the action this hook is associated with (PreToolUse/PostToolUse) + */ + action_id?: string | null; + /** + * Message Id + * @description ID of the message this hook is associated with (UserPromptSubmit) + */ + message_id?: string | null; + /** + * Hook Input + * @description The input data that was passed to the hook + */ + hook_input?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__hook_execution__HookExecutionEvent-Output__1'; + }; + /** + * HookMatcher + * @description Matches events to hooks based on patterns. + * + * Supports exact match, wildcard (*), and regex (auto-detected or /pattern/). + */ + 'HookMatcher-Input': { + /** + * Matcher + * @default * + */ + matcher?: string; + /** Hooks */ + hooks?: components['schemas']['HookDefinition'][]; + }; + /** + * HookMatcher + * @description Matches events to hooks based on patterns. + * + * Supports exact match, wildcard (*), and regex (auto-detected or /pattern/). + */ + 'HookMatcher-Output': { + /** + * Matcher + * @default * + */ + matcher?: string; + /** Hooks */ + hooks?: components['schemas']['HookDefinition'][]; + }; + /** + * HookType + * @description Types of hooks that can be executed. + * @enum {string} + */ + HookType: 'command' | 'prompt'; + /** + * HooksRequest + * @description Request body for loading hooks. + */ + HooksRequest: { + /** + * Project Dir + * @description Workspace directory path for project hooks + */ + project_dir?: string | null; + }; + /** + * HooksResponse + * @description Response containing hooks configuration. + */ + HooksResponse: { + /** @description Hook configuration loaded from the workspace, or None if not found */ + hook_config?: components['schemas']['HookConfig-Output'] | null; + }; + /** + * Icon + * @description An icon for display in user interfaces. + */ + Icon: { + /** Src */ + src: string; + /** Mimetype */ + mimeType?: string | null; + /** Sizes */ + sizes?: string[] | null; + } & { + [key: string]: unknown; + }; + /** ImageContent */ + ImageContent: { + /** + * Cache Prompt + * @default false + */ + cache_prompt?: boolean; + /** + * Type + * @default image + * @constant + */ + type?: 'image'; + /** Image Urls */ + image_urls: string[]; + }; + /** + * InputMetadata + * @description Metadata for task skill inputs. + */ + InputMetadata: { + /** + * Name + * @description Name of the input parameter + */ + name: string; + /** + * Description + * @description Description of the input parameter + */ + description: string; + }; + /** InvokeSkillAction */ + InvokeSkillAction: { + /** + * Name + * @description Name of the loaded skill to invoke. + */ + name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__invoke_skill__InvokeSkillAction-Output__1'; + }; + /** InvokeSkillActionWithRisk */ + InvokeSkillActionWithRisk: { + /** + * Name + * @description Name of the loaded skill to invoke. + */ + name: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__InvokeSkillActionWithRisk-Output__1'; + }; + /** InvokeSkillObservation */ + InvokeSkillObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Skill Name + * @description Name of the skill this observation corresponds to. + */ + skill_name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__invoke_skill__InvokeSkillObservation-Output__1'; + }; + /** + * InvokeSkillTool + * @description Built-in tool for explicit invocation of progressive-disclosure skills. + */ + InvokeSkillTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__invoke_skill__InvokeSkillTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * IterativeRefinementConfig + * @description Configuration for iterative refinement based on critic feedback. + * + * When attached to a CriticBase, the Conversation.run() method will + * automatically retry the task if the critic score is below the threshold. + * + * Example: + * critic = APIBasedCritic( + * server_url="...", + * api_key="...", + * model_name="critic", + * iterative_refinement=IterativeRefinementConfig( + * success_threshold=0.7, + * max_iterations=3, + * ), + * ) + * agent = Agent(llm=llm, tools=tools, critic=critic) + * conversation = Conversation(agent=agent, workspace=workspace) + * conversation.send_message("Create a calculator module...") + * conversation.run() # Will automatically retry if critic score < 0.7 + */ + IterativeRefinementConfig: { + /** + * Success Threshold + * @description Score threshold (0-1) to consider task successful. + * @default 0.6 + */ + success_threshold?: number; + /** + * Max Iterations + * @description Maximum number of iterations before giving up. + * @default 3 + */ + max_iterations?: number; + }; + /** + * KeywordTrigger + * @description Trigger for keyword-based skills. + * + * These skills are activated when specific keywords appear in the user's query. + */ + KeywordTrigger: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: 'keyword'; + /** Keywords */ + keywords: string[]; + }; + /** + * LLM + * @description Language model interface for OpenHands agents. + * + * The LLM class provides a unified interface for interacting with various + * language models through the litellm library. It handles model configuration, + * API authentication, retry logic, and tool calling capabilities. + * + * Attributes: + * model: Model name (e.g., "claude-sonnet-4-20250514"). + * api_key: API key for authentication. + * base_url: Custom API base URL. + * num_retries: Number of retry attempts for failed requests. + * timeout: Request timeout in seconds. + * + * Example: + * ```python + * from openhands.sdk import LLM + * from pydantic import SecretStr + * + * llm = LLM( + * model="claude-sonnet-4-20250514", + * api_key=SecretStr("your-api-key"), + * usage_id="my-agent" + * ) + * # Use with agent or conversation + * ``` + */ + 'LLM-Input': { + /** + * Model + * @description Model name. + * @default claude-sonnet-4-20250514 + */ + model?: string; + /** + * Api Key + * @description API key. + */ + api_key?: string | null; + /** + * Base Url + * @description Custom base URL. + */ + base_url?: string | null; + /** + * Api Version + * @description API version (e.g., Azure). + */ + api_version?: string | null; + /** Aws Access Key Id */ + aws_access_key_id?: string | null; + /** Aws Secret Access Key */ + aws_secret_access_key?: string | null; + /** Aws Session Token */ + aws_session_token?: string | null; + /** Aws Region Name */ + aws_region_name?: string | null; + /** Aws Profile Name */ + aws_profile_name?: string | null; + /** Aws Role Name */ + aws_role_name?: string | null; + /** Aws Session Name */ + aws_session_name?: string | null; + /** Aws Bedrock Runtime Endpoint */ + aws_bedrock_runtime_endpoint?: string | null; + /** + * Openrouter Site Url + * @default https://docs.all-hands.dev/ + */ + openrouter_site_url?: string; + /** + * Openrouter App Name + * @default OpenHands + */ + openrouter_app_name?: string; + /** + * Num Retries + * @default 5 + */ + num_retries?: number; + /** + * Retry Multiplier + * @default 8 + */ + retry_multiplier?: number; + /** + * Retry Min Wait + * @default 8 + */ + retry_min_wait?: number; + /** + * Retry Max Wait + * @default 64 + */ + retry_max_wait?: number; + /** + * Timeout + * @description HTTP timeout in seconds. Default is 300s (5 minutes). Set to None to disable timeout (not recommended for production). + * @default 300 + */ + timeout?: number | null; + /** + * Max Message Chars + * @description Approx max chars in each event/content sent to the LLM. + * @default 30000 + */ + max_message_chars?: number; + /** + * Temperature + * @description Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses. + */ + temperature?: number | null; + /** + * Top P + * @description Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs. + */ + top_p?: number | null; + /** Top K */ + top_k?: number | null; + /** + * Max Input Tokens + * @description The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4). + */ + max_input_tokens?: number | null; + /** + * Max Output Tokens + * @description The maximum number of output tokens. This is sent to the LLM. + */ + max_output_tokens?: number | null; + /** + * Model Canonical Name + * @description Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups. + */ + model_canonical_name?: string | null; + /** + * Extra Headers + * @description Optional HTTP headers to forward to LiteLLM requests. + */ + extra_headers?: { + [key: string]: string; + } | null; + /** + * Input Cost Per Token + * @description The cost per input token. This will available in logs for user. + */ + input_cost_per_token?: number | null; + /** + * Output Cost Per Token + * @description The cost per output token. This will available in logs for user. + */ + output_cost_per_token?: number | null; + /** Ollama Base Url */ + ollama_base_url?: string | null; + /** + * Stream + * @description Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens. + * @default false + */ + stream?: boolean; + /** + * Drop Params + * @default true + */ + drop_params?: boolean; + /** + * Modify Params + * @description Modify params allows litellm to do transformations like adding a default message, when a message is empty. + * @default true + */ + modify_params?: boolean; + /** + * Disable Vision + * @description If model is vision capable, this option allows to disable image processing (useful for cost reduction). + */ + disable_vision?: boolean | null; + /** + * Disable Stop Word + * @description Disable using of stop word. + * @default false + */ + disable_stop_word?: boolean | null; + /** + * Caching Prompt + * @description Enable caching of prompts. + * @default true + */ + caching_prompt?: boolean; + /** + * Log Completions + * @description Enable logging of completions. + * @default false + */ + log_completions?: boolean; + /** + * Log Completions Folder + * @description The folder to log LLM completions to. Required if log_completions is True. + * @default logs/completions + */ + log_completions_folder?: string; + /** + * Custom Tokenizer + * @description A custom tokenizer to use for token counting. + */ + custom_tokenizer?: string | null; + /** + * Native Tool Calling + * @description Whether to use native tool calling. + * @default true + */ + native_tool_calling?: boolean; + /** + * Force String Serializer + * @description Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq. + */ + force_string_serializer?: boolean | null; + /** + * Reasoning Effort + * @description The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', 'xhigh', or 'none'. Can apply to all reasoning models. + * @default high + */ + reasoning_effort?: ('low' | 'medium' | 'high' | 'xhigh' | 'none') | null; + /** + * 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. + */ + reasoning_summary?: ('auto' | 'concise' | 'detailed') | null; + /** + * Enable Encrypted Reasoning + * @description If True, ask for ['reasoning.encrypted_content'] in Responses API include. + * @default true + */ + enable_encrypted_reasoning?: boolean; + /** + * Prompt Cache Retention + * @description Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others. + * @default 24h + */ + prompt_cache_retention?: string | null; + /** + * Extended Thinking Budget + * @description The budget tokens for extended thinking, supported by Anthropic models. + * @default 200000 + */ + extended_thinking_budget?: number | null; + /** + * Seed + * @description The seed to use for random number generation. + */ + seed?: number | null; + /** + * Usage Id + * @description Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking. + * @default default + */ + usage_id?: string; + /** + * Litellm Extra Body + * @description Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True} + */ + litellm_extra_body?: { + [key: string]: unknown; + }; + /** @description Optional fallback strategy for trying alternate LLMs on transient failure. Construct with FallbackStrategy(fallback_llms=[...]).Excluded from serialization; must be reconfigured after load. */ + fallback_strategy?: components['schemas']['FallbackStrategy'] | null; + }; + /** + * LLM + * @description Language model interface for OpenHands agents. + * + * The LLM class provides a unified interface for interacting with various + * language models through the litellm library. It handles model configuration, + * API authentication, retry logic, and tool calling capabilities. + * + * Attributes: + * model: Model name (e.g., "claude-sonnet-4-20250514"). + * api_key: API key for authentication. + * base_url: Custom API base URL. + * num_retries: Number of retry attempts for failed requests. + * timeout: Request timeout in seconds. + * + * Example: + * ```python + * from openhands.sdk import LLM + * from pydantic import SecretStr + * + * llm = LLM( + * model="claude-sonnet-4-20250514", + * api_key=SecretStr("your-api-key"), + * usage_id="my-agent" + * ) + * # Use with agent or conversation + * ``` + */ + 'LLM-Output': { + /** + * Model + * @description Model name. + * @default claude-sonnet-4-20250514 + */ + model?: string; + /** + * Api Key + * @description API key. + */ + api_key?: string | null; + /** + * Base Url + * @description Custom base URL. + */ + base_url?: string | null; + /** + * Api Version + * @description API version (e.g., Azure). + */ + api_version?: string | null; + /** Aws Access Key Id */ + aws_access_key_id?: string | null; + /** Aws Secret Access Key */ + aws_secret_access_key?: string | null; + /** Aws Session Token */ + aws_session_token?: string | null; + /** Aws Region Name */ + aws_region_name?: string | null; + /** Aws Profile Name */ + aws_profile_name?: string | null; + /** Aws Role Name */ + aws_role_name?: string | null; + /** Aws Session Name */ + aws_session_name?: string | null; + /** Aws Bedrock Runtime Endpoint */ + aws_bedrock_runtime_endpoint?: string | null; + /** + * Openrouter Site Url + * @default https://docs.all-hands.dev/ + */ + openrouter_site_url?: string; + /** + * Openrouter App Name + * @default OpenHands + */ + openrouter_app_name?: string; + /** + * Num Retries + * @default 5 + */ + num_retries?: number; + /** + * Retry Multiplier + * @default 8 + */ + retry_multiplier?: number; + /** + * Retry Min Wait + * @default 8 + */ + retry_min_wait?: number; + /** + * Retry Max Wait + * @default 64 + */ + retry_max_wait?: number; + /** + * Timeout + * @description HTTP timeout in seconds. Default is 300s (5 minutes). Set to None to disable timeout (not recommended for production). + * @default 300 + */ + timeout?: number | null; + /** + * Max Message Chars + * @description Approx max chars in each event/content sent to the LLM. + * @default 30000 + */ + max_message_chars?: number; + /** + * Temperature + * @description Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses. + */ + temperature?: number | null; + /** + * Top P + * @description Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs. + */ + top_p?: number | null; + /** Top K */ + top_k?: number | null; + /** + * Max Input Tokens + * @description The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4). + */ + max_input_tokens?: number | null; + /** + * Max Output Tokens + * @description The maximum number of output tokens. This is sent to the LLM. + */ + max_output_tokens?: number | null; + /** + * Model Canonical Name + * @description Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups. + */ + model_canonical_name?: string | null; + /** + * Extra Headers + * @description Optional HTTP headers to forward to LiteLLM requests. + */ + extra_headers?: { + [key: string]: string; + } | null; + /** + * Input Cost Per Token + * @description The cost per input token. This will available in logs for user. + */ + input_cost_per_token?: number | null; + /** + * Output Cost Per Token + * @description The cost per output token. This will available in logs for user. + */ + output_cost_per_token?: number | null; + /** Ollama Base Url */ + ollama_base_url?: string | null; + /** + * Stream + * @description Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens. + * @default false + */ + stream?: boolean; + /** + * Drop Params + * @default true + */ + drop_params?: boolean; + /** + * Modify Params + * @description Modify params allows litellm to do transformations like adding a default message, when a message is empty. + * @default true + */ + modify_params?: boolean; + /** + * Disable Vision + * @description If model is vision capable, this option allows to disable image processing (useful for cost reduction). + */ + disable_vision?: boolean | null; + /** + * Disable Stop Word + * @description Disable using of stop word. + * @default false + */ + disable_stop_word?: boolean | null; + /** + * Caching Prompt + * @description Enable caching of prompts. + * @default true + */ + caching_prompt?: boolean; + /** + * Log Completions + * @description Enable logging of completions. + * @default false + */ + log_completions?: boolean; + /** + * Log Completions Folder + * @description The folder to log LLM completions to. Required if log_completions is True. + * @default logs/completions + */ + log_completions_folder?: string; + /** + * Custom Tokenizer + * @description A custom tokenizer to use for token counting. + */ + custom_tokenizer?: string | null; + /** + * Native Tool Calling + * @description Whether to use native tool calling. + * @default true + */ + native_tool_calling?: boolean; + /** + * Force String Serializer + * @description Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq. + */ + force_string_serializer?: boolean | null; + /** + * Reasoning Effort + * @description The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', 'xhigh', or 'none'. Can apply to all reasoning models. + * @default high + */ + reasoning_effort?: ('low' | 'medium' | 'high' | 'xhigh' | 'none') | null; + /** + * 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. + */ + reasoning_summary?: ('auto' | 'concise' | 'detailed') | null; + /** + * Enable Encrypted Reasoning + * @description If True, ask for ['reasoning.encrypted_content'] in Responses API include. + * @default true + */ + enable_encrypted_reasoning?: boolean; + /** + * Prompt Cache Retention + * @description Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others. + * @default 24h + */ + prompt_cache_retention?: string | null; + /** + * Extended Thinking Budget + * @description The budget tokens for extended thinking, supported by Anthropic models. + * @default 200000 + */ + extended_thinking_budget?: number | null; + /** + * Seed + * @description The seed to use for random number generation. + */ + seed?: number | null; + /** + * Usage Id + * @description Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking. + * @default default + */ + usage_id?: string; + /** + * Litellm Extra Body + * @description Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True} + */ + litellm_extra_body?: { + [key: string]: unknown; + }; + }; + /** + * LLMCompletionLogEvent + * @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. + */ + LLMCompletionLogEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Filename + * @description The intended filename for this log (relative to log directory) + */ + filename: string; + /** + * Log Data + * @description The JSON-encoded log data to be written to the file + */ + log_data: string; + /** + * Model Name + * @description The model name for context + * @default unknown + */ + model_name?: string; + /** + * Usage Id + * @description The LLM usage_id that produced this log + * @default default + */ + usage_id?: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_completion_log__LLMCompletionLogEvent-Output__1'; + }; + /** + * LLMSecurityAnalyzer + * @description LLM-based security analyzer. + * + * This analyzer respects the security_risk attribute that can be set by the LLM + * when generating actions, similar to OpenHands' LLMRiskAnalyzer. + * + * It provides a lightweight security analysis approach that leverages the LLM's + * understanding of action context and potential risks. + */ + 'LLMSecurityAnalyzer-Input': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__llm_analyzer__LLMSecurityAnalyzer-Input__1'; + }; + /** + * LLMSecurityAnalyzer + * @description LLM-based security analyzer. + * + * This analyzer respects the security_risk attribute that can be set by the LLM + * when generating actions, similar to OpenHands' LLMRiskAnalyzer. + * + * It provides a lightweight security analysis approach that leverages the LLM's + * understanding of action context and potential risks. + */ + 'LLMSecurityAnalyzer-Output': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__llm_analyzer__LLMSecurityAnalyzer-Output__1'; + }; + /** + * LLMSummarizingCondenser + * @description LLM-based condenser that summarizes forgotten events. + * + * Uses an independent LLM (stored in the `llm` attribute) for generating summaries + * of forgotten events. The optional `agent_llm` parameter passed to condense() is + * the LLM used by the agent for token counting purposes, and you should not assume + * it is the same as the one defined in this condenser. + */ + 'LLMSummarizingCondenser-Input': { + llm: components['schemas']['LLM-Input']; + /** + * Max Size + * @default 240 + */ + max_size?: number; + /** Max Tokens */ + max_tokens?: number | null; + /** + * Keep First + * @default 2 + */ + keep_first?: number; + /** + * Minimum Progress + * @default 0.1 + */ + minimum_progress?: number; + /** + * Hard Context Reset Max Retries + * @default 5 + */ + hard_context_reset_max_retries?: number; + /** + * Hard Context Reset Context Scaling + * @default 0.8 + */ + hard_context_reset_context_scaling?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Input__1'; + }; + /** + * LLMSummarizingCondenser + * @description LLM-based condenser that summarizes forgotten events. + * + * Uses an independent LLM (stored in the `llm` attribute) for generating summaries + * of forgotten events. The optional `agent_llm` parameter passed to condense() is + * the LLM used by the agent for token counting purposes, and you should not assume + * it is the same as the one defined in this condenser. + */ + 'LLMSummarizingCondenser-Output': { + llm: components['schemas']['LLM-Output']; + /** + * Max Size + * @default 240 + */ + max_size?: number; + /** Max Tokens */ + max_tokens?: number | null; + /** + * Keep First + * @default 2 + */ + keep_first?: number; + /** + * Minimum Progress + * @default 0.1 + */ + minimum_progress?: number; + /** + * Hard Context Reset Max Retries + * @default 5 + */ + hard_context_reset_max_retries?: number; + /** + * Hard Context Reset Context Scaling + * @default 0.8 + */ + hard_context_reset_context_scaling?: number; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Output__1'; + }; + /** + * ListDirectoryAction + * @description Schema for list directory operation. + */ + ListDirectoryAction: { + /** + * Dir Path + * @description The path to the directory to list. Defaults to current directory. + * @default . + */ + dir_path?: string; + /** + * Recursive + * @description Whether to list subdirectories recursively (up to 2 levels). + * @default false + */ + recursive?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__list_directory__definition__ListDirectoryAction-Output__1'; + }; + /** ListDirectoryActionWithRisk */ + ListDirectoryActionWithRisk: { + /** + * Dir Path + * @description The path to the directory to list. Defaults to current directory. + * @default . + */ + dir_path?: string; + /** + * Recursive + * @description Whether to list subdirectories recursively (up to 2 levels). + * @default false + */ + recursive?: boolean; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__ListDirectoryActionWithRisk-Output__1'; + }; + /** + * ListDirectoryObservation + * @description Observation from listing a directory. + */ + ListDirectoryObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Dir Path + * @description The directory path that was listed. + */ + dir_path?: string | null; + /** + * Entries + * @description List of files and directories found. + */ + entries?: components['schemas']['FileEntry'][]; + /** + * Total Count + * @description Total number of entries found. + * @default 0 + */ + total_count?: number; + /** + * Is Truncated + * @description Whether the listing was truncated due to too many entries. + * @default false + */ + is_truncated?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__list_directory__definition__ListDirectoryObservation-Output__1'; + }; + /** + * ListDirectoryTool + * @description Tool for listing directory contents with metadata. + */ + ListDirectoryTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__list_directory__definition__ListDirectoryTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * LocalWorkspace + * @description Local workspace implementation that operates on the host filesystem. + * + * LocalWorkspace provides direct access to the local filesystem and command execution + * environment. It's suitable for development and testing scenarios where the agent + * should operate directly on the host system. + * + * Example: + * >>> workspace = LocalWorkspace(working_dir="/path/to/project") + * >>> with workspace: + * ... result = workspace.execute_command("ls -la") + * ... content = workspace.read_file("README.md") + */ + 'LocalWorkspace-Input': { + /** + * Working Dir + * @description The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings. + */ + working_dir: string; + /** + * Kind + * @constant + */ + kind?: 'LocalWorkspace'; + }; + /** + * LocalWorkspace + * @description Local workspace implementation that operates on the host filesystem. + * + * LocalWorkspace provides direct access to the local filesystem and command execution + * environment. It's suitable for development and testing scenarios where the agent + * should operate directly on the host system. + * + * Example: + * >>> workspace = LocalWorkspace(working_dir="/path/to/project") + * >>> with workspace: + * ... result = workspace.execute_command("ls -la") + * ... content = workspace.read_file("README.md") + */ + 'LocalWorkspace-Output': { + /** + * Working Dir + * @description The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings. + */ + working_dir: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__workspace__local__LocalWorkspace-Output__1'; + }; + /** + * LookupSecret + * @description A secret looked up from some external url + */ + 'LookupSecret-Input': { + /** + * Description + * @description Optional description for this secret + */ + description?: string | null; + /** Url */ + url: string; + /** Headers */ + headers?: { + [key: string]: string; + }; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__secret__secrets__LookupSecret-Input__1'; + }; + /** + * LookupSecret + * @description A secret looked up from some external url + */ + 'LookupSecret-Output': { + /** + * Description + * @description Optional description for this secret + */ + description?: string | null; + /** Url */ + url: string; + /** Headers */ + headers?: { + [key: string]: string; + }; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__secret__secrets__LookupSecret-Output__1'; + }; + /** + * MCPToolAction + * @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. + */ + MCPToolAction: { + /** + * Data + * @description Dynamic data fields from the tool call + */ + data?: { + [key: string]: unknown; + }; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__mcp__definition__MCPToolAction-Output__1'; + }; + /** MCPToolActionWithRisk */ + MCPToolActionWithRisk: { + /** + * Data + * @description Dynamic data fields from the tool call + */ + data?: { + [key: string]: unknown; + }; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__MCPToolActionWithRisk-Output__1'; + }; + /** + * MCPToolDefinition + * @description MCP Tool that wraps an MCP client and provides tool functionality. + */ + MCPToolDefinition: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** @description The MCP tool definition. */ + mcp_tool: components['schemas']['mcp__types__Tool']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__mcp__tool__MCPToolDefinition-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * MCPToolObservation + * @description Observation from MCP tool execution. + */ + MCPToolObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Tool Name + * @description Name of the tool that was called + */ + tool_name: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__mcp__definition__MCPToolObservation-Output__1'; + }; + /** Message */ + Message: { + /** + * Role + * @enum {string} + */ + role: 'user' | 'system' | 'assistant' | 'tool'; + /** Content */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** Tool Calls */ + tool_calls?: components['schemas']['MessageToolCall'][] | null; + /** Tool Call Id */ + tool_call_id?: string | null; + /** Name */ + name?: string | null; + /** + * Reasoning Content + * @description Intermediate reasoning/thinking content from reasoning models + */ + reasoning_content?: string | null; + /** + * Thinking Blocks + * @description Raw Anthropic thinking blocks for extended thinking feature + */ + thinking_blocks?: ( + | components['schemas']['ThinkingBlock'] + | components['schemas']['RedactedThinkingBlock'] + )[]; + /** @description OpenAI Responses reasoning item from model output */ + responses_reasoning_item?: components['schemas']['ReasoningItemModel'] | null; + }; + /** + * MessageEvent + * @description Message from either agent or user. + * + * This is originally the "MessageAction", but it suppose not to be tool call. + */ + MessageEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @enum {string} + */ + source: 'agent' | 'user' | 'environment' | 'hook'; + /** @description The exact LLM message for this message event */ + llm_message: components['schemas']['Message']; + /** + * Llm Response Id + * @description Completion or Response ID of the LLM response that generated this eventIf the source != 'agent', this field is None + */ + llm_response_id?: string | null; + /** + * Activated Skills + * @description List of activated skill name + */ + activated_skills?: string[]; + /** + * Extended Content + * @description List of content added by agent context + */ + extended_content?: components['schemas']['TextContent'][]; + /** + * Sender + * @description Optional identifier of the sender. Can be used to track message origin in multi-agent scenarios. + */ + sender?: string | null; + /** @description Optional critic evaluation of this message and preceding history. */ + critic_result?: components['schemas']['CriticResult'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_convertible__message__MessageEvent-Output__1'; + }; + /** + * 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. + */ + MessageToolCall: { + /** + * Id + * @description Canonical tool call id + */ + id: string; + /** + * Responses Item Id + * @description Original Responses function_call.id, echoed verbatim on replay + */ + responses_item_id?: string | null; + /** + * Name + * @description Tool/function name + */ + name: string; + /** + * Arguments + * @description JSON string of arguments + */ + arguments: string; + /** + * Origin + * @description Originating API family + * @enum {string} + */ + origin: 'completion' | 'responses'; + }; + /** + * Metrics + * @description Metrics class can record various metrics during running and evaluation. + * We track: + * - accumulated_cost and costs + * - max_budget_per_task (budget limit) + * - A list of ResponseLatency + * - A list of TokenUsage (one per call). + */ + Metrics: { + /** + * Model Name + * @description Name of the model + * @default default + */ + model_name?: string; + /** + * Accumulated Cost + * @description Total accumulated cost, must be non-negative + * @default 0 + */ + accumulated_cost?: number; + /** + * Max Budget Per Task + * @description Maximum budget per task + */ + max_budget_per_task?: number | null; + /** @description Accumulated token usage across all calls */ + accumulated_token_usage?: components['schemas']['TokenUsage'] | null; + /** + * Costs + * @description List of individual costs + */ + costs?: components['schemas']['Cost'][]; + /** + * Response Latencies + * @description List of response latencies + */ + response_latencies?: components['schemas']['ResponseLatency'][]; + /** + * Token Usages + * @description List of token usage records + */ + token_usages?: components['schemas']['TokenUsage'][]; + }; + /** + * MetricsSnapshot + * @description A snapshot of metrics at a point in time. + * + * Does not include lists of individual costs, latencies, or token usages. + */ + MetricsSnapshot: { + /** + * Model Name + * @description Name of the model + * @default default + */ + model_name?: string; + /** + * Accumulated Cost + * @description Total accumulated cost, must be non-negative + * @default 0 + */ + accumulated_cost?: number; + /** + * Max Budget Per Task + * @description Maximum budget per task + */ + max_budget_per_task?: number | null; + /** @description Accumulated token usage across all calls */ + accumulated_token_usage?: components['schemas']['TokenUsage'] | null; + }; + /** + * ModelsResponse + * @description Response containing the list of available LLM models. + */ + ModelsResponse: { + /** Models */ + models: string[]; + }; + /** NeverConfirm */ + 'NeverConfirm-Input': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__confirmation_policy__NeverConfirm-Input__1'; + }; + /** NeverConfirm */ + 'NeverConfirm-Output': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__confirmation_policy__NeverConfirm-Output__1'; + }; + /** + * NoOpCondenser + * @description Simple condenser that returns a view un-manipulated. + * + * Primarily intended for testing purposes. + */ + 'NoOpCondenser-Input': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Input__1'; + }; + /** + * NoOpCondenser + * @description Simple condenser that returns a view un-manipulated. + * + * Primarily intended for testing purposes. + */ + 'NoOpCondenser-Output': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Output__1'; + }; + Observation: + | components['schemas']['MCPToolObservation'] + | components['schemas']['FinishObservation'] + | components['schemas']['InvokeSkillObservation'] + | components['schemas']['SwitchLLMObservation'] + | components['schemas']['ThinkObservation'] + | components['schemas']['BrowserObservation'] + | components['schemas']['DelegateObservation'] + | components['schemas']['FileEditorObservation'] + | components['schemas']['EditObservation'] + | components['schemas']['ListDirectoryObservation'] + | components['schemas']['ReadFileObservation'] + | components['schemas']['WriteFileObservation'] + | components['schemas']['GlobObservation'] + | components['schemas']['GrepObservation'] + | components['schemas']['PlanningFileEditorObservation'] + | components['schemas']['TaskObservation'] + | components['schemas']['TaskTrackerObservation'] + | components['schemas']['TerminalObservation']; + /** ObservationEvent */ + ObservationEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Tool Name + * @description The tool name that this observation is responding to + */ + tool_name: string; + /** + * Tool Call Id + * @description The tool call id that this observation is responding to + */ + tool_call_id: string; + /** @description The observation (tool call) sent to LLM */ + observation: components['schemas']['Observation']; + /** + * Action Id + * @description The action id that this observation is responding to + */ + action_id: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_convertible__observation__ObservationEvent-Output__1'; + }; + /** + * OrgConfig + * @description Configuration for loading organization-level skills. + */ + OrgConfig: { + /** + * Repository + * @description Selected repository (e.g., 'owner/repo') + */ + repository: string; + /** + * Provider + * @description Git provider type: github, gitlab, azure, bitbucket + */ + provider: string; + /** + * Org Repo Url + * @description Pre-authenticated Git URL for the organization repository. Contains sensitive credentials - handle with care and avoid logging. + */ + org_repo_url: string; + /** + * Org Name + * @description Organization name + */ + org_name: string; + }; + /** + * PassCritic + * @description Critic that always returns success. + * + * This critic can be used when no evaluation is needed or when + * all instances should be considered successful regardless of their output. + */ + 'PassCritic-Input': { + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__pass_critic__PassCritic-Input__1'; + }; + /** + * PassCritic + * @description Critic that always returns success. + * + * This critic can be used when no evaluation is needed or when + * all instances should be considered successful regardless of their output. + */ + 'PassCritic-Output': { + /** + * Mode + * @description When to run critic evaluation: + * - 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact) + * - 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action) + * @default finish_and_message + * @enum {string} + */ + mode?: 'finish_and_message' | 'all_actions'; + /** @description Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations. */ + iterative_refinement?: components['schemas']['IterativeRefinementConfig'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__critic__impl__pass_critic__PassCritic-Output__1'; + }; + /** + * PatternSecurityAnalyzer + * @description Catch dangerous agent actions through deterministic signature scanning. + * + * Use this when you want fast, local, no-network threat detection at the + * action boundary. It returns ``SecurityRisk.HIGH``, ``MEDIUM``, or ``LOW`` + * -- pair it with ``ConfirmRisky`` to decide what gets confirmed. + * + * The key design choice: shell-destructive patterns only scan what the + * agent will *execute* (tool arguments), never what it *thought about* + * (reasoning text). Injection patterns scan everything, because + * "ignore all previous instructions" is dangerous wherever it appears. + * + * Normalization is always on -- invisible characters and fullwidth + * substitutions are collapsed before matching. + * + * Example:: + * + * from openhands.sdk.security import PatternSecurityAnalyzer, ConfirmRisky + * + * analyzer = PatternSecurityAnalyzer() + * policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM) + */ + 'PatternSecurityAnalyzer-Input': { + /** + * High Patterns + * @description HIGH patterns scanned against executable fields only + */ + high_patterns?: [string, string, string][]; + /** + * Medium Patterns + * @description MEDIUM patterns scanned against executable fields only + */ + medium_patterns?: [string, string, string][]; + /** + * Injection High Patterns + * @description HIGH patterns scanned against all fields + */ + injection_high_patterns?: [string, string, string][]; + /** + * Injection Medium Patterns + * @description MEDIUM patterns scanned against all fields + */ + injection_medium_patterns?: [string, string, string][]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__defense_in_depth__pattern__PatternSecurityAnalyzer-Input__1'; + }; + /** + * PatternSecurityAnalyzer + * @description Catch dangerous agent actions through deterministic signature scanning. + * + * Use this when you want fast, local, no-network threat detection at the + * action boundary. It returns ``SecurityRisk.HIGH``, ``MEDIUM``, or ``LOW`` + * -- pair it with ``ConfirmRisky`` to decide what gets confirmed. + * + * The key design choice: shell-destructive patterns only scan what the + * agent will *execute* (tool arguments), never what it *thought about* + * (reasoning text). Injection patterns scan everything, because + * "ignore all previous instructions" is dangerous wherever it appears. + * + * Normalization is always on -- invisible characters and fullwidth + * substitutions are collapsed before matching. + * + * Example:: + * + * from openhands.sdk.security import PatternSecurityAnalyzer, ConfirmRisky + * + * analyzer = PatternSecurityAnalyzer() + * policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM) + */ + 'PatternSecurityAnalyzer-Output': { + /** + * High Patterns + * @description HIGH patterns scanned against executable fields only + */ + high_patterns?: [string, string, string][]; + /** + * Medium Patterns + * @description MEDIUM patterns scanned against executable fields only + */ + medium_patterns?: [string, string, string][]; + /** + * Injection High Patterns + * @description HIGH patterns scanned against all fields + */ + injection_high_patterns?: [string, string, string][]; + /** + * Injection Medium Patterns + * @description MEDIUM patterns scanned against all fields + */ + injection_medium_patterns?: [string, string, string][]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__defense_in_depth__pattern__PatternSecurityAnalyzer-Output__1'; + }; + /** + * PauseEvent + * @description Event indicating that the agent execution was paused by user request. + */ + PauseEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default user + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__user_action__PauseEvent-Output__1'; + }; + /** + * PipelineCondenser + * @description A condenser that applies a sequence of condensers in order. + * + * All condensers are defined primarily by their `condense` method, which takes a + * `View` and an optional `agent_llm` parameter, returning either a new `View` or a + * `Condensation` event. That means we can chain multiple condensers together by + * passing `View`s along and exiting early if any condenser returns a `Condensation`. + * + * For example: + * + * # Use the pipeline condenser to chain multiple other condensers together + * condenser = PipelineCondenser(condensers=[ + * CondenserA(...), + * CondenserB(...), + * CondenserC(...), + * ]) + * + * result = condenser.condense(view, agent_llm=agent_llm) + * + * # Doing the same thing without the pipeline condenser requires more boilerplate + * # for the monadic chaining + * other_result = view + * + * if isinstance(other_result, View): + * other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm) + * + * if isinstance(other_result, View): + * other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm) + * + * if isinstance(other_result, View): + * other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm) + * + * assert result == other_result + */ + 'PipelineCondenser-Input': { + /** Condensers */ + condensers: components['schemas']['CondenserBase-Input'][]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Input__1'; + }; + /** + * PipelineCondenser + * @description A condenser that applies a sequence of condensers in order. + * + * All condensers are defined primarily by their `condense` method, which takes a + * `View` and an optional `agent_llm` parameter, returning either a new `View` or a + * `Condensation` event. That means we can chain multiple condensers together by + * passing `View`s along and exiting early if any condenser returns a `Condensation`. + * + * For example: + * + * # Use the pipeline condenser to chain multiple other condensers together + * condenser = PipelineCondenser(condensers=[ + * CondenserA(...), + * CondenserB(...), + * CondenserC(...), + * ]) + * + * result = condenser.condense(view, agent_llm=agent_llm) + * + * # Doing the same thing without the pipeline condenser requires more boilerplate + * # for the monadic chaining + * other_result = view + * + * if isinstance(other_result, View): + * other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm) + * + * if isinstance(other_result, View): + * other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm) + * + * if isinstance(other_result, View): + * other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm) + * + * assert result == other_result + */ + 'PipelineCondenser-Output': { + /** Condensers */ + condensers: components['schemas']['CondenserBase-Output'][]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Output__1'; + }; + /** + * PlanningFileEditorAction + * @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. + */ + PlanningFileEditorAction: { + /** + * Command + * @description The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`. + * @enum {string} + */ + command: 'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'; + /** + * Path + * @description Absolute path to file or directory. + */ + path: string; + /** + * File Text + * @description Required parameter of `create` command, with the content of the file to be created. + */ + file_text?: string | null; + /** + * Old Str + * @description Required parameter of `str_replace` command containing the string in `path` to replace. + */ + old_str?: string | null; + /** + * New Str + * @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. + */ + new_str?: string | null; + /** + * Insert Line + * @description Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. + */ + insert_line?: number | null; + /** + * View Range + * @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. + */ + view_range?: number[] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorAction-Output__1'; + }; + /** PlanningFileEditorActionWithRisk */ + PlanningFileEditorActionWithRisk: { + /** + * Command + * @description The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`. + * @enum {string} + */ + command: 'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'; + /** + * Path + * @description Absolute path to file or directory. + */ + path: string; + /** + * File Text + * @description Required parameter of `create` command, with the content of the file to be created. + */ + file_text?: string | null; + /** + * Old Str + * @description Required parameter of `str_replace` command containing the string in `path` to replace. + */ + old_str?: string | null; + /** + * New Str + * @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. + */ + new_str?: string | null; + /** + * Insert Line + * @description Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`. + */ + insert_line?: number | null; + /** + * View Range + * @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. + */ + view_range?: number[] | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__PlanningFileEditorActionWithRisk-Output__1'; + }; + /** + * PlanningFileEditorObservation + * @description Observation from planning file editor operations. + * + * Inherits from FileEditorObservation - same structure, just different type. + */ + PlanningFileEditorObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Command + * @description The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`. + * @enum {string} + */ + command: 'view' | 'create' | 'str_replace' | 'insert' | 'undo_edit'; + /** + * Path + * @description The file path that was edited. + */ + path?: string | null; + /** + * Prev Exist + * @description Indicates if the file previously existed. If not, it was created. + * @default true + */ + prev_exist?: boolean; + /** + * Old Content + * @description The content of the file before the edit. + */ + old_content?: string | null; + /** + * New Content + * @description The content of the file after the edit. + */ + new_content?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorObservation-Output__1'; + }; + /** + * PlanningFileEditorTool + * @description A planning file editor tool with read-all, edit-PLAN.md-only access. + */ + PlanningFileEditorTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__planning_file_editor__definition__PlanningFileEditorTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * PluginSource + * @description Specification for a plugin to load. + * + * This model describes where to find a plugin and is used by load_plugins() + * to fetch and load plugins from various sources. + * + * Examples: + * >>> # GitHub repository + * >>> PluginSource(source="github:owner/repo", ref="v1.0.0") + * + * >>> # Plugin from monorepo subdirectory + * >>> PluginSource( + * ... source="github:owner/monorepo", + * ... repo_path="plugins/my-plugin" + * ... ) + * + * >>> # Local path + * >>> PluginSource(source="/path/to/plugin") + */ + PluginSource: { + /** + * Source + * @description Plugin source: 'github:owner/repo', any git URL, or local path + */ + source: string; + /** + * Ref + * @description Optional branch, tag, or commit (only for git sources) + */ + ref?: string | null; + /** + * Repo Path + * @description Subdirectory path within the git repository (e.g., 'plugins/my-plugin' for monorepos). Only relevant for git sources, not local paths. + */ + repo_path?: string | null; + }; + /** + * PolicyRailSecurityAnalyzer + * @description Catch composed threats that plain regex signatures would miss. + * + * Use this when you need to detect threats defined by *combinations* + * of tokens (e.g., ``curl`` piped to ``bash``) rather than individual + * signatures. While these rails *could* each be expressed as a single + * regex, keeping them as named rules with per-segment evaluation makes + * the threat model more interpretable, the rules easier to maintain, + * and the audit trail clearer than a flat pattern list. + * + * Evaluates normalized executable segments only -- reasoning text is + * never scanned. + * + * Returns ``SecurityRisk.HIGH`` when a rail fires, ``LOW`` otherwise. + * Pair with ``ConfirmRisky`` and compose via ``EnsembleSecurityAnalyzer``. + * + * v1 rails: fetch-to-exec, raw-disk-op, catastrophic-delete. + * + * Example:: + * + * from openhands.sdk.security import PolicyRailSecurityAnalyzer + * + * analyzer = PolicyRailSecurityAnalyzer() + * # risk = analyzer.security_risk(action) + */ + 'PolicyRailSecurityAnalyzer-Input': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__defense_in_depth__policy_rails__PolicyRailSecurityAnalyzer-Input__1'; + }; + /** + * PolicyRailSecurityAnalyzer + * @description Catch composed threats that plain regex signatures would miss. + * + * Use this when you need to detect threats defined by *combinations* + * of tokens (e.g., ``curl`` piped to ``bash``) rather than individual + * signatures. While these rails *could* each be expressed as a single + * regex, keeping them as named rules with per-segment evaluation makes + * the threat model more interpretable, the rules easier to maintain, + * and the audit trail clearer than a flat pattern list. + * + * Evaluates normalized executable segments only -- reasoning text is + * never scanned. + * + * Returns ``SecurityRisk.HIGH`` when a rail fires, ``LOW`` otherwise. + * Pair with ``ConfirmRisky`` and compose via ``EnsembleSecurityAnalyzer``. + * + * v1 rails: fetch-to-exec, raw-disk-op, catastrophic-delete. + * + * Example:: + * + * from openhands.sdk.security import PolicyRailSecurityAnalyzer + * + * analyzer = PolicyRailSecurityAnalyzer() + * # risk = analyzer.security_risk(action) + */ + 'PolicyRailSecurityAnalyzer-Output': { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__security__defense_in_depth__policy_rails__PolicyRailSecurityAnalyzer-Output__1'; + }; + /** + * ProfileDetailResponse + * @description ``config.api_key`` is always nulled; use ``api_key_set`` instead. + */ + ProfileDetailResponse: { + /** Name */ + name: string; + /** Config */ + config: { + [key: string]: unknown; + }; + /** + * Api Key Set + * @default false + */ + api_key_set?: boolean; + }; + /** ProfileInfo */ + ProfileInfo: { + /** Name */ + name: string; + /** Model */ + model?: string | null; + /** Base Url */ + base_url?: string | null; + /** + * Api Key Set + * @default false + */ + api_key_set?: boolean; + }; + /** ProfileListResponse */ + ProfileListResponse: { + /** Profiles */ + profiles: components['schemas']['ProfileInfo'][]; + /** Active Profile */ + active_profile?: string | null; + }; + /** ProfileMutationResponse */ + ProfileMutationResponse: { + /** Name */ + name: string; + /** Message */ + message: string; + }; + /** + * ProvidersResponse + * @description Response containing the list of available LLM providers. + */ + ProvidersResponse: { + /** Providers */ + providers: string[]; + }; + /** + * ReadFileAction + * @description Schema for read file operation. + */ + ReadFileAction: { + /** + * File Path + * @description The path to the file to read. + */ + file_path: string; + /** + * Offset + * @description Optional: The 0-based line number to start reading from. Use for paginating through large files. + */ + offset?: number | null; + /** + * Limit + * @description Optional: Maximum number of lines to read. Use with 'offset' to paginate through large files. + */ + limit?: number | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__read_file__definition__ReadFileAction-Output__1'; + }; + /** ReadFileActionWithRisk */ + ReadFileActionWithRisk: { + /** + * File Path + * @description The path to the file to read. + */ + file_path: string; + /** + * Offset + * @description Optional: The 0-based line number to start reading from. Use for paginating through large files. + */ + offset?: number | null; + /** + * Limit + * @description Optional: Maximum number of lines to read. Use with 'offset' to paginate through large files. + */ + limit?: number | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__ReadFileActionWithRisk-Output__1'; + }; + /** + * ReadFileObservation + * @description Observation from reading a file. + */ + ReadFileObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * File Path + * @description The file path that was read. + */ + file_path: string; + /** + * File Content + * @description The content read from the file. + * @default + */ + file_content?: string; + /** + * Is Truncated + * @description Whether the content was truncated due to size limits. + * @default false + */ + is_truncated?: boolean; + /** + * Lines Shown + * @description If truncated, the range of lines shown (start, end) - 1-indexed. + */ + lines_shown?: [number, number] | null; + /** + * Total Lines + * @description Total number of lines in the file. + */ + total_lines?: number | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__read_file__definition__ReadFileObservation-Output__1'; + }; + /** + * ReadFileTool + * @description Tool for reading file contents with pagination support. + */ + ReadFileTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__read_file__definition__ReadFileTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * ReasoningItemModel + * @description OpenAI Responses reasoning item (non-stream, subset we consume). + * + * Do not log or render encrypted_content. + */ + ReasoningItemModel: { + /** Id */ + id?: string | null; + /** Summary */ + summary?: string[]; + /** Content */ + content?: string[] | null; + /** Encrypted Content */ + encrypted_content?: string | null; + /** Status */ + status?: string | null; + }; + /** + * 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. + */ + RedactedThinkingBlock: { + /** + * Type + * @default redacted_thinking + * @constant + */ + type?: 'redacted_thinking'; + /** + * Data + * @description The redacted thinking content + */ + data: string; + }; + /** + * RemoteWorkspace + * @description Remote workspace implementation that connects to an OpenHands agent server. + * + * RemoteWorkspace provides access to a sandboxed environment running on a remote + * OpenHands agent server. This is the recommended approach for production deployments + * as it provides better isolation and security. + * + * Supports optional completion callbacks on exit via environment variables: + * - ``AUTOMATION_CALLBACK_URL`` — URL to POST completion status to + * - ``AUTOMATION_CALLBACK_API_KEY`` — Bearer token for callback auth (optional) + * - ``AUTOMATION_RUN_ID`` — Run ID to include in callback payload (optional) + * + * Example: + * >>> workspace = RemoteWorkspace( + * ... host="https://agent-server.example.com", + * ... working_dir="/workspace" + * ... ) + * >>> with workspace: + * ... result = workspace.execute_command("ls -la") + * ... content = workspace.read_file("README.md") + */ + RemoteWorkspace: { + /** + * Working Dir + * @description The working directory for agent operations and tool execution. + */ + working_dir: string; + /** + * Host + * @description The remote host URL for the workspace. + */ + host: string; + /** + * Api Key + * @description API key for authenticating with the remote host. + */ + api_key?: string | null; + /** + * Read Timeout + * @description Timeout in seconds for reading operations of httpx.Client. + * @default 600 + */ + read_timeout?: number; + /** + * Max Connections + * @description Maximum number of connections for httpx.Client. None means no limit, useful for running many conversations in parallel. + */ + max_connections?: number | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__workspace__remote__base__RemoteWorkspace-Output__1'; + }; + /** RenameProfileRequest */ + RenameProfileRequest: { + /** New Name */ + new_name: string; + }; + /** + * ResponseLatency + * @description Metric tracking the round-trip time per completion call. + */ + ResponseLatency: { + /** Model */ + model: string; + /** + * Latency + * @description Latency must be non-negative + */ + latency: number; + /** Response Id */ + response_id: string; + }; + /** + * SandboxConfig + * @description Configuration for loading sandbox-specific skills. + */ + SandboxConfig: { + /** + * Exposed Urls + * @description List of exposed URLs from the sandbox + */ + exposed_urls?: components['schemas']['ExposedUrl'][]; + }; + /** SaveProfileRequest */ + SaveProfileRequest: { + llm: components['schemas']['LLM-Input']; + /** + * Include Secrets + * @description Whether to persist the API key with the profile. + * @default true + */ + include_secrets?: boolean; + }; + /** + * SecretCreateRequest + * @description Request model for PUT /api/settings/secrets. + * + * Creates or updates a secret with the given name and value. + */ + SecretCreateRequest: { + /** Name */ + name: string; + /** + * Value + * Format: password + */ + value: string; + /** Description */ + description?: string | null; + }; + /** + * SecretItemResponse + * @description Response model for a secret item (without value). + * + * Used in list responses and as the response for create/update operations. + */ + SecretItemResponse: { + /** Name */ + name: string; + /** Description */ + description?: string | null; + }; + /** + * SecretRegistry + * @description Manages secrets and injects them into bash commands when needed. + * + * The secret registry stores a mapping of secret keys to SecretSources + * that retrieve the actual secret values. When a bash command is about to be + * executed, it scans the command for any secret keys and injects the corresponding + * environment variables. + * + * Secret sources will redact / encrypt their sensitive values as appropriate when + * serializing, depending on the content of the context. If a context is present + * and contains a 'cipher' object, this is used for encryption. If it contains a + * boolean 'expose_secrets' flag set to True, secrets are dunped in plain text. + * Otherwise secrets are redacted. + * + * Additionally, it tracks the latest exported values to enable consistent masking + * even when callable secrets fail on subsequent calls. + */ + SecretRegistry: { + /** Secret Sources */ + secret_sources?: { + [key: string]: components['schemas']['SecretSource-Output']; + }; + }; + 'SecretSource-Input': + | components['schemas']['LookupSecret-Input'] + | components['schemas']['StaticSecret-Input']; + 'SecretSource-Output': + | components['schemas']['LookupSecret-Output'] + | components['schemas']['StaticSecret-Output']; + /** + * SecretsListResponse + * @description Response model for GET /api/settings/secrets. + * + * Lists all available secrets with their names and descriptions. + * Values are never included in list responses. + */ + SecretsListResponse: { + /** Secrets */ + secrets: components['schemas']['SecretItemResponse'][]; + }; + 'SecurityAnalyzerBase-Input': + | components['schemas']['PatternSecurityAnalyzer-Input'] + | components['schemas']['PolicyRailSecurityAnalyzer-Input'] + | components['schemas']['EnsembleSecurityAnalyzer-Input'] + | components['schemas']['GraySwanAnalyzer-Input'] + | components['schemas']['LLMSecurityAnalyzer-Input']; + 'SecurityAnalyzerBase-Output': + | components['schemas']['PatternSecurityAnalyzer-Output'] + | components['schemas']['PolicyRailSecurityAnalyzer-Output'] + | components['schemas']['EnsembleSecurityAnalyzer-Output'] + | components['schemas']['GraySwanAnalyzer-Output'] + | components['schemas']['LLMSecurityAnalyzer-Output']; + /** + * 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 {string} + */ + SecurityRisk: 'UNKNOWN' | 'LOW' | 'MEDIUM' | 'HIGH'; + /** + * SendMessageRequest + * @description Payload to send a message to the agent. + */ + SendMessageRequest: { + /** + * Role + * @default user + * @enum {string} + */ + role?: 'user' | 'system' | 'assistant' | 'tool'; + /** Content */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Run + * @description Whether the agent loop should automatically run if not running + * @default false + */ + run?: boolean; + }; + /** + * ServerErrorEvent + * @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. + */ + ServerErrorEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @description The source of this event + * @enum {string} + */ + source: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Code + * @description Code for the error - typically an error type + */ + code: string; + /** + * Detail + * @description Details about the error + */ + detail: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__agent_server__models__ServerErrorEvent-Output__1'; + }; + /** ServerInfo */ + ServerInfo: { + /** Uptime */ + uptime: number; + /** Idle Time */ + idle_time: number; + /** + * Title + * @default OpenHands Agent Server + */ + title?: string; + /** Version */ + version?: string; + /** Sdk Version */ + sdk_version?: string; + /** Tools Version */ + tools_version?: string; + /** Workspace Version */ + workspace_version?: string; + /** Build Git Sha */ + build_git_sha?: string; + /** Build Git Ref */ + build_git_ref?: string; + /** Python Version */ + python_version?: string; + /** Usable Tools */ + usable_tools?: string[]; + /** + * Docs + * @default /docs + */ + docs?: string; + /** + * Redoc + * @default /redoc + */ + redoc?: string; + }; + /** + * SetConfirmationPolicyRequest + * @description Payload to set confirmation policy for a conversation. + */ + SetConfirmationPolicyRequest: { + /** @description The confirmation policy to set */ + policy: components['schemas']['ConfirmationPolicyBase-Input']; + }; + /** + * SetSecurityAnalyzerRequest + * @description Payload to set security analyzer for a conversation + */ + SetSecurityAnalyzerRequest: { + /** @description The security analyzer to set */ + security_analyzer: components['schemas']['SecurityAnalyzerBase-Input'] | null; + }; + /** + * SettingProminence + * @enum {string} + */ + SettingProminence: 'critical' | 'major' | 'minor'; + /** SettingsChoice */ + SettingsChoice: { + /** Value */ + value: boolean | number | string; + /** Label */ + label: string; + }; + /** SettingsFieldSchema */ + SettingsFieldSchema: { + /** Key */ + key: string; + /** Label */ + label: string; + /** Description */ + description?: string | null; + /** Section */ + section: string; + /** Section Label */ + section_label: string; + /** + * Value Type + * @enum {string} + */ + value_type: 'string' | 'integer' | 'number' | 'boolean' | 'array' | 'object'; + /** Default */ + default?: unknown; + /** @default minor */ + prominence?: components['schemas']['SettingProminence']; + /** Depends On */ + depends_on?: string[]; + /** + * Secret + * @default false + */ + secret?: boolean; + /** Choices */ + choices?: components['schemas']['SettingsChoice'][]; + /** + * Variant + * @description When set, the field only applies to the named ``AgentSettings`` variant (``'openhands'`` or ``'acp'``). The GUI filters fields by the user's current variant; fields with ``variant=None`` are shown regardless. + */ + variant?: string | null; + }; + /** + * SettingsResponse + * @description Response model for GET /api/settings. + * + * Contains the full settings payload including agent configuration, + * conversation settings, and a flag indicating if an LLM API key is set. + * + * The ``agent_settings`` and ``conversation_settings`` fields are raw dicts + * because the server controls secret serialization via context. Use the + * typed accessor methods for validation: + * + * Example:: + * + * response = SettingsResponse.model_validate(api_response.json()) + * agent = response.get_agent_settings() # Returns AgentSettingsConfig + * conv = response.get_conversation_settings() # Returns ConversationSettings + */ + SettingsResponse: { + /** Agent Settings */ + agent_settings: { + [key: string]: unknown; + }; + /** Conversation Settings */ + conversation_settings: { + [key: string]: unknown; + }; + /** Llm Api Key Is Set */ + llm_api_key_is_set: boolean; + }; + /** SettingsSchema */ + SettingsSchema: { + /** Model Name */ + model_name: string; + /** Sections */ + sections: components['schemas']['SettingsSectionSchema'][]; + }; + /** SettingsSectionSchema */ + SettingsSectionSchema: { + /** Key */ + key: string; + /** Label */ + label: string; + /** Fields */ + fields: components['schemas']['SettingsFieldSchema'][]; + /** + * Variant + * @description When set, this section only applies to the named ``AgentSettings`` variant (e.g. ``'openhands'`` or ``'acp'``). The GUI filters sections by the current ``agent_kind`` value; sections with ``variant=None`` are always shown. + */ + variant?: string | null; + }; + /** + * SettingsUpdateRequest + * @description Request model for PATCH /api/settings. + * + * Supports partial updates via diff objects that are deep-merged with + * existing settings. + */ + SettingsUpdateRequest: { + /** Agent Settings Diff */ + agent_settings_diff?: { + [key: string]: unknown; + } | null; + /** Conversation Settings Diff */ + conversation_settings_diff?: { + [key: string]: unknown; + } | null; + }; + /** + * Skill + * @description A skill provides specialized knowledge or functionality. + * + * Skill behavior depends on format (is_agentskills_format) and trigger: + * + * AgentSkills format (SKILL.md files): + * - Always listed in with name, description, location + * - Agent reads full content on demand (progressive disclosure) + * - If has triggers: content is ALSO auto-injected when triggered + * + * Legacy OpenHands format: + * - With triggers: Listed in , content injected on trigger + * - Without triggers (None): Full content in , always active + * + * This model supports both OpenHands-specific fields and AgentSkills standard + * fields (https://agentskills.io/specification) for cross-platform compatibility. + */ + Skill: { + /** Name */ + name: string; + /** Content */ + content: string; + /** + * Trigger + * @description Trigger determines when skill content is auto-injected. None = no auto-injection (for AgentSkills: agent reads on demand; for legacy: full content always in system prompt). KeywordTrigger = auto-inject when keywords appear in user messages. TaskTrigger = auto-inject for specific tasks, may require user input. + */ + trigger?: + | (components['schemas']['KeywordTrigger'] | components['schemas']['TaskTrigger']) + | null; + /** + * Source + * @description The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill. + */ + source?: string | null; + /** + * Mcp Tools + * @description MCP tools configuration for the skill (repo skills only). It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format + */ + mcp_tools?: { + [key: string]: unknown; + } | null; + /** + * Inputs + * @description Input metadata for the skill (task skills only) + */ + inputs?: components['schemas']['InputMetadata'][]; + /** + * Is Agentskills Format + * @description Whether this skill was loaded from a SKILL.md file following the AgentSkills standard. AgentSkills-format skills use progressive disclosure: always listed in with name, description, and location. If the skill also has triggers, content is auto-injected when triggered AND agent can read file anytime. + * @default false + */ + is_agentskills_format?: boolean; + /** + * Version + * @description Skill version (AgentSkills standard field). + * @default 1.0.0 + */ + version?: string; + /** + * Description + * @description A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to the skill's source path. + */ + description?: string | null; + /** + * License + * @description The license under which the skill is distributed. AgentSkills standard field (e.g., 'Apache-2.0', 'MIT'). + */ + license?: string | null; + /** + * Compatibility + * @description Environment requirements or compatibility notes for the skill. AgentSkills standard field (e.g., 'Requires git and docker'). + */ + compatibility?: string | null; + /** + * Metadata + * @description Arbitrary key-value metadata for the skill. AgentSkills standard field for extensibility. + */ + metadata?: { + [key: string]: string; + } | null; + /** + * Allowed Tools + * @description List of pre-approved tools for this skill. AgentSkills standard field (parsed from space-delimited string). + */ + allowed_tools?: string[] | null; + /** + * Disable Model Invocation + * @description Whether this skill can only be activated by trigger matching and should not be advertised to the model for direct invocation. + * @default false + */ + disable_model_invocation?: boolean; + /** @description Resource directories for the skill (scripts/, references/, assets/). AgentSkills standard field. Only populated for SKILL.md directory format. */ + resources?: components['schemas']['SkillResources'] | null; + }; + /** + * SkillInfo + * @description Skill information returned by the API. + */ + SkillInfo: { + /** Name */ + name: string; + /** + * Type + * @enum {string} + */ + type: 'repo' | 'knowledge' | 'agentskills'; + /** Content */ + content: string; + /** Triggers */ + triggers?: string[]; + /** Source */ + source?: string | null; + /** Description */ + description?: string | null; + /** + * Is Agentskills Format + * @default false + */ + is_agentskills_format?: boolean; + /** + * Disable Model Invocation + * @default false + */ + disable_model_invocation?: boolean; + }; + /** + * SkillResources + * @description Resource directories for a skill (AgentSkills standard). + * + * Per the AgentSkills specification, skills can include: + * - scripts/: Executable scripts the agent can run + * - references/: Reference documentation and examples + * - assets/: Static assets (images, data files, etc.) + */ + SkillResources: { + /** + * Skill Root + * @description Root directory of the skill (absolute path) + */ + skill_root: string; + /** + * Scripts + * @description List of script files in scripts/ directory (relative paths) + */ + scripts?: string[]; + /** + * References + * @description List of reference files in references/ directory (relative paths) + */ + references?: string[]; + /** + * Assets + * @description List of asset files in assets/ directory (relative paths) + */ + assets?: string[]; + }; + /** + * SkillsRequest + * @description Request body for loading skills. + */ + SkillsRequest: { + /** + * Load Public + * @description Load public skills from OpenHands/extensions repo + * @default true + */ + load_public?: boolean; + /** + * Load User + * @description Load user skills from ~/.openhands/skills/ + * @default true + */ + load_user?: boolean; + /** + * Load Project + * @description Load project skills from workspace + * @default true + */ + load_project?: boolean; + /** + * Load Org + * @description Load organization-level skills + * @default true + */ + load_org?: boolean; + /** + * Marketplace Path + * @description Relative marketplace JSON path for public skills. Set to null to load all public skills. + * @default marketplaces/default.json + */ + marketplace_path?: string | null; + /** + * Project Dir + * @description Workspace directory path for project skills + */ + project_dir?: string | null; + /** @description Organization skills configuration */ + org_config?: components['schemas']['OrgConfig'] | null; + /** @description Sandbox skills configuration */ + sandbox_config?: components['schemas']['SandboxConfig'] | null; + }; + /** + * SkillsResponse + * @description Response containing all available skills. + */ + SkillsResponse: { + /** Skills */ + skills: components['schemas']['SkillInfo'][]; + /** + * Sources + * @description Count of skills loaded from each source + */ + sources?: { + [key: string]: number; + }; + }; + /** + * StartACPConversationRequest + * @description Deprecated compatibility alias for ACP-capable start requests. + * + * Use :class:`StartConversationRequest` instead. It now supports both regular + * OpenHands agents and ACP agents through the same request contract. + */ + StartACPConversationRequest: { + /** @description Working directory for agent operations and tool execution. */ + workspace: components['schemas']['LocalWorkspace-Input']; + /** + * Worktree + * @description If true and the workspace is already inside a git repository, create a dedicated git worktree for this conversation under `/tmp/conversation-worktrees//`. + * @default false + */ + worktree?: boolean; + /** + * Conversation Id + * @description Optional conversation ID. If not provided, a random UUID will be generated. + */ + conversation_id?: string | null; + /** + * @description Controls when the conversation will prompt the user before continuing. Defaults to never. + * @default { + * "kind": "NeverConfirm" + * } + */ + confirmation_policy?: components['schemas']['ConfirmationPolicyBase-Input']; + /** @description Optional security analyzer to evaluate action risks. */ + security_analyzer?: components['schemas']['SecurityAnalyzerBase-Input'] | null; + /** @description Initial message to pass to the LLM */ + initial_message?: components['schemas']['SendMessageRequest'] | null; + /** + * Max Iterations + * @description If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops. + * @default 500 + */ + max_iterations?: number; + /** + * Stuck Detection + * @description If true, the conversation will use stuck detection to prevent infinite loops. + * @default true + */ + stuck_detection?: boolean; + /** + * Secrets + * @description Secrets available in the conversation + */ + secrets?: { + [key: string]: components['schemas']['SecretSource-Input']; + }; + /** + * Secrets Encrypted + * @description If true, indicates that secret values in the agent configuration are cipher-encrypted and should be decrypted by the server before use. This enables secure round-tripping of settings through untrusted clients (e.g., frontend) that received encrypted values via the X-Expose-Secrets header. Flow: client calls GET /api/settings with X-Expose-Secrets: encrypted to receive cipher-encrypted secrets, then passes them in the agent config with secrets_encrypted=True so the server can decrypt them. + * @default false + */ + secrets_encrypted?: boolean; + /** + * Tool Module Qualnames + * @description Mapping of tool names to their module qualnames from the client's registry. These modules will be dynamically imported on the server to register the tools for this conversation. + */ + tool_module_qualnames?: { + [key: string]: string; + }; + /** + * Agent Definitions + * @description Agent definitions from the client's registry. These are registered on the server so that DelegateTool and TaskSetTool can see user-registered subagents. + */ + agent_definitions?: components['schemas']['AgentDefinition'][]; + /** + * Plugins + * @description List of plugins to load for this conversation. Plugins are loaded and their skills/MCP config are merged into the agent. Hooks are extracted and stored for runtime execution. + */ + plugins?: components['schemas']['PluginSource'][] | null; + /** @description Optional hook configuration for this conversation. Hooks are shell scripts that run at key lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, etc.). If both hook_config and plugins are provided, they are merged with explicit hooks running before plugin hooks. */ + hook_config?: components['schemas']['HookConfig-Input'] | null; + /** + * Tags + * @description Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. + */ + tags?: { + [key: string]: string; + }; + /** + * Autotitle + * @description If true, automatically generate a title for the conversation from the first user message. Precedence: title_llm_profile (if set and loads) → agent.llm → message truncation. + * @default true + */ + autotitle?: boolean; + /** + * Title Llm Profile + * @description Optional LLM profile name for title generation. If set, the LLM is loaded from LLMProfileStore (~/.openhands/profiles/) and used for LLM-based title generation. This enables using a fast/cheap model for titles regardless of the agent's main model. If not set (or profile loading fails), title generation falls back to the agent's LLM. + */ + title_llm_profile?: string | null; + /** + * Agent Settings + * @description Optional agent settings payload. If `agent` is omitted, this is validated with the AgentSettingsBase `agent_kind` discriminator and used to construct the concrete agent. + */ + agent_settings?: { + [key: string]: unknown; + } | null; + agent?: components['schemas']['AgentBase-Input']; + }; + /** + * StartConversationRequest + * @description Payload to create a new conversation. + * + * Supports any concrete :class:`AgentBase` implementation, including regular + * OpenHands agents and ACP agents. Clients may provide either a concrete + * ``agent`` payload or an ``agent_settings`` payload; when ``agent_settings`` + * is provided without ``agent``, the settings are validated with the + * ``agent_kind`` discriminator and converted to the appropriate agent type. + */ + StartConversationRequest: { + /** @description Working directory for agent operations and tool execution. */ + workspace: components['schemas']['LocalWorkspace-Input']; + /** + * Worktree + * @description If true and the workspace is already inside a git repository, create a dedicated git worktree for this conversation under `/tmp/conversation-worktrees//`. + * @default false + */ + worktree?: boolean; + /** + * Conversation Id + * @description Optional conversation ID. If not provided, a random UUID will be generated. + */ + conversation_id?: string | null; + /** + * @description Controls when the conversation will prompt the user before continuing. Defaults to never. + * @default { + * "kind": "NeverConfirm" + * } + */ + confirmation_policy?: components['schemas']['ConfirmationPolicyBase-Input']; + /** @description Optional security analyzer to evaluate action risks. */ + security_analyzer?: components['schemas']['SecurityAnalyzerBase-Input'] | null; + /** @description Initial message to pass to the LLM */ + initial_message?: components['schemas']['SendMessageRequest'] | null; + /** + * Max Iterations + * @description If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops. + * @default 500 + */ + max_iterations?: number; + /** + * Stuck Detection + * @description If true, the conversation will use stuck detection to prevent infinite loops. + * @default true + */ + stuck_detection?: boolean; + /** + * Secrets + * @description Secrets available in the conversation + */ + secrets?: { + [key: string]: components['schemas']['SecretSource-Input']; + }; + /** + * Secrets Encrypted + * @description If true, indicates that secret values in the agent configuration are cipher-encrypted and should be decrypted by the server before use. This enables secure round-tripping of settings through untrusted clients (e.g., frontend) that received encrypted values via the X-Expose-Secrets header. Flow: client calls GET /api/settings with X-Expose-Secrets: encrypted to receive cipher-encrypted secrets, then passes them in the agent config with secrets_encrypted=True so the server can decrypt them. + * @default false + */ + secrets_encrypted?: boolean; + /** + * Tool Module Qualnames + * @description Mapping of tool names to their module qualnames from the client's registry. These modules will be dynamically imported on the server to register the tools for this conversation. + */ + tool_module_qualnames?: { + [key: string]: string; + }; + /** + * Agent Definitions + * @description Agent definitions from the client's registry. These are registered on the server so that DelegateTool and TaskSetTool can see user-registered subagents. + */ + agent_definitions?: components['schemas']['AgentDefinition'][]; + /** + * Plugins + * @description List of plugins to load for this conversation. Plugins are loaded and their skills/MCP config are merged into the agent. Hooks are extracted and stored for runtime execution. + */ + plugins?: components['schemas']['PluginSource'][] | null; + /** @description Optional hook configuration for this conversation. Hooks are shell scripts that run at key lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, etc.). If both hook_config and plugins are provided, they are merged with explicit hooks running before plugin hooks. */ + hook_config?: components['schemas']['HookConfig-Input'] | null; + /** + * Tags + * @description Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. + */ + tags?: { + [key: string]: string; + }; + /** + * Autotitle + * @description If true, automatically generate a title for the conversation from the first user message. Precedence: title_llm_profile (if set and loads) → agent.llm → message truncation. + * @default true + */ + autotitle?: boolean; + /** + * Title Llm Profile + * @description Optional LLM profile name for title generation. If set, the LLM is loaded from LLMProfileStore (~/.openhands/profiles/) and used for LLM-based title generation. This enables using a fast/cheap model for titles regardless of the agent's main model. If not set (or profile loading fails), title generation falls back to the agent's LLM. + */ + title_llm_profile?: string | null; + /** + * Agent Settings + * @description Optional agent settings payload. If `agent` is omitted, this is validated with the AgentSettingsBase `agent_kind` discriminator and used to construct the concrete agent. + */ + agent_settings?: { + [key: string]: unknown; + } | null; + agent?: components['schemas']['AgentBase-Input']; + }; + /** + * StaticSecret + * @description A secret stored locally + */ + 'StaticSecret-Input': { + /** + * Description + * @description Optional description for this secret + */ + description?: string | null; + /** Value */ + value?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__secret__secrets__StaticSecret-Input__1'; + }; + /** + * StaticSecret + * @description A secret stored locally + */ + 'StaticSecret-Output': { + /** + * Description + * @description Optional description for this secret + */ + description?: string | null; + /** Value */ + value?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__secret__secrets__StaticSecret-Output__1'; + }; + /** + * StreamingDeltaEvent + * @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. + */ + StreamingDeltaEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default agent + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** Content */ + content?: string | null; + /** Reasoning Content */ + reasoning_content?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__streaming_delta__StreamingDeltaEvent-Output__1'; + }; + /** SubdirectoryEntry */ + SubdirectoryEntry: { + /** Name */ + name: string; + /** Path */ + path: string; + }; + /** SubdirectoryPage */ + SubdirectoryPage: { + /** Items */ + items: components['schemas']['SubdirectoryEntry'][]; + /** Next Page Id */ + next_page_id?: string | null; + }; + /** Success */ + Success: { + /** + * Success + * @default true + */ + success?: boolean; + }; + /** + * SwitchLLMAction + * @description Action for switching this conversation to a saved LLM profile. + */ + SwitchLLMAction: { + /** + * Profile Name + * @description Name of the saved LLM profile to use for future agent steps. + */ + profile_name: string; + /** + * Reason + * @description Brief reason why this profile is a better fit for the next step. + */ + reason: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__switch_llm__SwitchLLMAction-Output__1'; + }; + /** SwitchLLMActionWithRisk */ + SwitchLLMActionWithRisk: { + /** + * Profile Name + * @description Name of the saved LLM profile to use for future agent steps. + */ + profile_name: string; + /** + * Reason + * @description Brief reason why this profile is a better fit for the next step. + */ + reason: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__SwitchLLMActionWithRisk-Output__1'; + }; + /** + * SwitchLLMObservation + * @description Observation returned after switching this conversation's LLM profile. + */ + SwitchLLMObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Profile Name + * @description Name of the profile that the tool attempted to activate. + */ + profile_name: string; + /** + * Reason + * @description Reason the agent gave for attempting this LLM profile switch. + */ + reason?: string | null; + /** + * Active Model + * @description Model configured by the activated profile, when available. + */ + active_model?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__switch_llm__SwitchLLMObservation-Output__1'; + }; + /** + * SwitchLLMTool + * @description Tool for switching a conversation to a saved LLM profile. + */ + SwitchLLMTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__switch_llm__SwitchLLMTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * SyncResponse + * @description Response from skill sync operation. + */ + SyncResponse: { + /** + * Status + * @enum {string} + */ + status: 'success' | 'error'; + /** Message */ + message: string; + }; + /** + * SystemPromptEvent + * @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. + */ + SystemPromptEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default agent + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** @description The system prompt text */ + system_prompt: components['schemas']['TextContent']; + /** + * Tools + * @description List of tools as ToolDefinition objects + */ + tools: components['schemas']['ToolDefinition'][]; + /** @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). */ + dynamic_context?: components['schemas']['TextContent'] | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_convertible__system__SystemPromptEvent-Output__1'; + }; + /** + * TaskAction + * @description Schema for launching a sub-agent task. + */ + TaskAction: { + /** + * Description + * @description A short (3-5 word) description of the task. + */ + description?: string | null; + /** + * Prompt + * @description The task for the agent to perform. + */ + prompt: string; + /** + * Subagent Type + * @description The type of specialized agent to use for this task. + * @default general-purpose + */ + subagent_type?: string; + /** + * Resume + * @description Task ID of the task to resume from. + */ + resume?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task__definition__TaskAction-Output__1'; + }; + /** TaskActionWithRisk */ + TaskActionWithRisk: { + /** + * Description + * @description A short (3-5 word) description of the task. + */ + description?: string | null; + /** + * Prompt + * @description The task for the agent to perform. + */ + prompt: string; + /** + * Subagent Type + * @description The type of specialized agent to use for this task. + * @default general-purpose + */ + subagent_type?: string; + /** + * Resume + * @description Task ID of the task to resume from. + */ + resume?: string | null; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__TaskActionWithRisk-Output__1'; + }; + /** TaskItem */ + TaskItem: { + /** + * Title + * @description A brief title for the task. + */ + title: string; + /** + * Notes + * @description Additional details or notes about the task. + * @default + */ + notes?: string; + /** + * Status + * @description The current status of the task. One of 'todo', 'in_progress', or 'done'. + * @default todo + * @enum {string} + */ + status?: 'todo' | 'in_progress' | 'done'; + }; + /** + * TaskObservation + * @description Observation from a task execution. + */ + TaskObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Task Id + * @description The unique identifier of the task. + */ + task_id: string; + /** + * Subagent + * @description The subagent of the task. + */ + subagent: string; + /** + * Status + * @description The status of the task. + */ + status: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task__definition__TaskObservation-Output__1'; + }; + /** + * TaskTool + * @description Tool for launching (blocking) sub-agent tasks. + */ + TaskTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task__definition__TaskTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * 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), + * ], + * ) + */ + TaskToolSet: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task__definition__TaskToolSet-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * TaskTrackerAction + * @description An action where the agent writes or updates a task list for task management. + */ + TaskTrackerAction: { + /** + * Command + * @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. + * @default view + * @enum {string} + */ + command?: 'view' | 'plan'; + /** + * Task List + * @description The full task list. Required parameter of `plan` command. + */ + task_list?: components['schemas']['TaskItem'][]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task_tracker__definition__TaskTrackerAction-Output__1'; + }; + /** TaskTrackerActionWithRisk */ + TaskTrackerActionWithRisk: { + /** + * Command + * @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. + * @default view + * @enum {string} + */ + command?: 'view' | 'plan'; + /** + * Task List + * @description The full task list. Required parameter of `plan` command. + */ + task_list?: components['schemas']['TaskItem'][]; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__TaskTrackerActionWithRisk-Output__1'; + }; + /** + * TaskTrackerObservation + * @description This data class represents the result of a task tracking operation. + */ + TaskTrackerObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Command + * @description The command that was executed: "view" or "plan". + * @enum {string} + */ + command: 'view' | 'plan'; + /** + * Task List + * @description The current task list + */ + task_list?: components['schemas']['TaskItem'][]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task_tracker__definition__TaskTrackerObservation-Output__1'; + }; + /** + * TaskTrackerTool + * @description A ToolDefinition subclass that automatically initializes a TaskTrackerExecutor. + */ + TaskTrackerTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__task_tracker__definition__TaskTrackerTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * TaskTrigger + * @description Trigger for task-specific skills. + * + * These skills are activated for specific task types and can modify prompts. + */ + TaskTrigger: { + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + type: 'task'; + /** Triggers */ + triggers: string[]; + }; + /** + * TerminalAction + * @description Schema for terminal command execution. + */ + TerminalAction: { + /** + * 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. + */ + command: string; + /** + * Is Input + * @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. + * @default false + */ + is_input?: boolean; + /** + * Timeout + * @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). + */ + timeout?: number | null; + /** + * Reset + * @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. + * @default false + */ + reset?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__terminal__definition__TerminalAction-Output__1'; + }; + /** TerminalActionWithRisk */ + TerminalActionWithRisk: { + /** + * 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. + */ + command: string; + /** + * Is Input + * @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. + * @default false + */ + is_input?: boolean; + /** + * Timeout + * @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). + */ + timeout?: number | null; + /** + * Reset + * @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. + * @default false + */ + reset?: boolean; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__TerminalActionWithRisk-Output__1'; + }; + /** + * TerminalObservation + * @description A ToolResult that can be rendered as a CLI output. + */ + TerminalObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * Command + * @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. + */ + command: string | null; + /** + * Exit Code + * @description The exit code of the command. -1 indicates the process hit the soft timeout and is not yet finished. + */ + exit_code?: number | null; + /** + * Timeout + * @description Whether the command execution timed out. + * @default false + */ + timeout?: boolean; + /** @description Additional metadata captured from PS1 after command execution. */ + metadata?: components['schemas']['CmdOutputMetadata']; + /** + * Full Output Save Dir + * @description Directory where full output files are saved + */ + full_output_save_dir?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__terminal__definition__TerminalObservation-Output__1'; + }; + /** + * TerminalTool + * @description A ToolDefinition subclass that automatically initializes a TerminalExecutor with auto-detection. + */ + TerminalTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__terminal__definition__TerminalTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** TextContent */ + TextContent: { + /** + * Cache Prompt + * @default false + */ + cache_prompt?: boolean; + /** + * Type + * @default text + * @constant + */ + type?: 'text'; + /** Text */ + text: string; + }; + /** + * ThinkAction + * @description Action for logging a thought without making any changes. + */ + ThinkAction: { + /** + * Thought + * @description The thought to log. + */ + thought: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__think__ThinkAction-Output__1'; + }; + /** ThinkActionWithRisk */ + ThinkActionWithRisk: { + /** + * Thought + * @description The thought to log. + */ + thought: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__ThinkActionWithRisk-Output__1'; + }; + /** + * ThinkObservation + * @description Observation returned after logging a thought. + * The ThinkAction itself contains the thought logged so no extra + * fields are needed here. + */ + ThinkObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__think__ThinkObservation-Output__1'; + }; + /** + * ThinkTool + * @description Tool for logging thoughts without making changes. + */ + ThinkTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__tool__builtins__think__ThinkTool-Output__1'; + /** Title */ + readonly title: 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. + */ + ThinkingBlock: { + /** + * Type + * @default thinking + * @constant + */ + type?: 'thinking'; + /** + * Thinking + * @description The thinking content + */ + thinking: string; + /** + * Signature + * @description Cryptographic signature for the thinking block + */ + signature?: string | null; + }; + /** + * TokenEvent + * @description Event from VLLM representing token IDs used in LLM interaction. + */ + TokenEvent: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @enum {string} + */ + source: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Prompt Token Ids + * @description The exact prompt token IDs for this message event + */ + prompt_token_ids: number[]; + /** + * Response Token Ids + * @description The exact response token IDs for this message event + */ + response_token_ids: number[]; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__token__TokenEvent-Output__1'; + }; + /** + * TokenUsage + * @description Metric tracking detailed token usage per completion call. + */ + TokenUsage: { + /** + * Model + * @default + */ + model?: string; + /** + * Prompt Tokens + * @description Prompt tokens must be non-negative + * @default 0 + */ + prompt_tokens?: number; + /** + * Completion Tokens + * @description Completion tokens must be non-negative + * @default 0 + */ + completion_tokens?: number; + /** + * Cache Read Tokens + * @description Cache read tokens must be non-negative + * @default 0 + */ + cache_read_tokens?: number; + /** + * Cache Write Tokens + * @description Cache write tokens must be non-negative + * @default 0 + */ + cache_write_tokens?: number; + /** + * Reasoning Tokens + * @description Reasoning tokens must be non-negative + * @default 0 + */ + reasoning_tokens?: number; + /** + * Context Window + * @description Context window must be non-negative + * @default 0 + */ + context_window?: number; + /** + * Per Turn Token + * @description Per turn tokens must be non-negative + * @default 0 + */ + per_turn_token?: number; + /** + * Response Id + * @default + */ + response_id?: string; + }; + /** + * Tool + * @description Defines a tool to be initialized for the agent. + * + * This is only used in agent-sdk for type schema for server use. + */ + 'Tool-Input': { + /** + * Name + * @description Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage. + * @example TerminalTool + * @example FileEditorTool + * @example TaskTrackerTool + */ + name: string; + /** + * Params + * @description Parameters for the tool's .create() method, e.g., {'working_dir': '/app'} + * @example { + * "working_dir": "/workspace" + * } + */ + params?: { + [key: string]: unknown; + }; + }; + ToolDefinition: + | components['schemas']['MCPToolDefinition'] + | components['schemas']['FinishTool'] + | components['schemas']['InvokeSkillTool'] + | components['schemas']['SwitchLLMTool'] + | components['schemas']['ThinkTool'] + | components['schemas']['BrowserClickTool'] + | components['schemas']['BrowserCloseTabTool'] + | components['schemas']['BrowserGetContentTool'] + | components['schemas']['BrowserGetStateTool'] + | components['schemas']['BrowserGetStorageTool'] + | components['schemas']['BrowserGoBackTool'] + | components['schemas']['BrowserListTabsTool'] + | components['schemas']['BrowserNavigateTool'] + | components['schemas']['BrowserScrollTool'] + | components['schemas']['BrowserSetStorageTool'] + | components['schemas']['BrowserStartRecordingTool'] + | components['schemas']['BrowserStopRecordingTool'] + | components['schemas']['BrowserSwitchTabTool'] + | components['schemas']['BrowserToolSet'] + | components['schemas']['BrowserTypeTool'] + | components['schemas']['DelegateTool'] + | components['schemas']['FileEditorTool'] + | components['schemas']['EditTool'] + | components['schemas']['ListDirectoryTool'] + | components['schemas']['ReadFileTool'] + | components['schemas']['WriteFileTool'] + | components['schemas']['GlobTool'] + | components['schemas']['GrepTool'] + | components['schemas']['PlanningFileEditorTool'] + | components['schemas']['TaskTool'] + | components['schemas']['TaskToolSet'] + | components['schemas']['TaskTrackerTool'] + | components['schemas']['TerminalTool']; + /** + * ToolExecution + * @description Execution-related properties for a tool. + */ + ToolExecution: { + /** Tasksupport */ + taskSupport?: ('forbidden' | 'optional' | 'required') | null; + } & { + [key: string]: unknown; + }; + /** + * UpdateConversationRequest + * @description Payload to update conversation metadata. + */ + UpdateConversationRequest: { + /** + * Title + * @description New conversation title + */ + title?: string | null; + /** + * Tags + * @description Key-value tags to set on the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. Replaces all existing tags when provided. + */ + tags?: { + [key: string]: string; + } | null; + }; + /** + * UpdateSecretsRequest + * @description Payload to update secrets in a conversation. + */ + UpdateSecretsRequest: { + /** + * Secrets + * @description Dictionary mapping secret keys to values + */ + secrets: { + [key: string]: components['schemas']['SecretSource-Input']; + }; + }; + /** + * UserRejectObservation + * @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") + */ + UserRejectObservation: { + /** + * Id + * @description Unique event id (ULID/UUID) + */ + id?: string; + /** + * Timestamp + * @description Event timestamp + */ + timestamp?: string; + /** + * Source + * @default environment + * @enum {string} + */ + source?: 'agent' | 'user' | 'environment' | 'hook'; + /** + * Tool Name + * @description The tool name that this observation is responding to + */ + tool_name: string; + /** + * Tool Call Id + * @description The tool call id that this observation is responding to + */ + tool_call_id: string; + /** + * Rejection Reason + * @description Reason for rejecting the action + * @default User rejected the action + */ + rejection_reason?: string; + /** + * Rejection Source + * @description Source of the rejection: 'user' for confirmation mode rejections, 'hook' for PreToolUse hook blocks + * @default user + * @enum {string} + */ + rejection_source?: 'user' | 'hook'; + /** + * Action Id + * @description The action id that this observation is responding to + */ + action_id: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__sdk__event__llm_convertible__observation__UserRejectObservation-Output__1'; + }; + /** + * VSCodeUrlResponse + * @description Response model for VSCode URL. + */ + VSCodeUrlResponse: { + /** Url */ + url: string | null; + }; + /** ValidationError */ + ValidationError: { + /** Location */ + loc: (string | number)[]; + /** Message */ + msg: string; + /** Error Type */ + type: string; + /** Input */ + input?: unknown; + /** Context */ + ctx?: Record; + }; + /** + * VerifiedModelsResponse + * @description Response containing verified models organized by provider. + */ + VerifiedModelsResponse: { + /** Models */ + models: { + [key: string]: string[]; + }; + }; + /** + * WriteFileAction + * @description Schema for write file operation. + */ + WriteFileAction: { + /** + * File Path + * @description The path to the file to write to. + */ + file_path: string; + /** + * Content + * @description The content to write to the file. + */ + content: string; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__write_file__definition__WriteFileAction-Output__1'; + }; + /** WriteFileActionWithRisk */ + WriteFileActionWithRisk: { + /** + * File Path + * @description The path to the file to write to. + */ + file_path: string; + /** + * Content + * @description The content to write to the file. + */ + content: string; + /** + * @description The LLM's assessment of the safety risk of this action. + * @default UNKNOWN + */ + security_risk?: components['schemas']['SecurityRisk']; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'abc__WriteFileActionWithRisk-Output__1'; + }; + /** + * WriteFileObservation + * @description Observation from writing a file. + */ + WriteFileObservation: { + /** + * 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. + */ + content?: (components['schemas']['TextContent'] | components['schemas']['ImageContent'])[]; + /** + * Is Error + * @description Whether the observation indicates an error + * @default false + */ + is_error?: boolean; + /** + * File Path + * @description The file path that was written. + */ + file_path?: string | null; + /** + * Is New File + * @description Whether a new file was created. + * @default false + */ + is_new_file?: boolean; + /** + * Old Content + * @description The previous content of the file (if it existed). + */ + old_content?: string | null; + /** + * New Content + * @description The new content written to the file. + */ + new_content?: string | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__write_file__definition__WriteFileObservation-Output__1'; + }; + /** + * WriteFileTool + * @description Tool for writing complete file contents. + */ + WriteFileTool: { + /** Description */ + description: string; + /** Action Type */ + action_type: string; + /** Observation Type */ + observation_type?: string | null; + annotations?: components['schemas']['openhands__sdk__tool__tool__ToolAnnotations'] | null; + /** Meta */ + meta?: { + [key: string]: unknown; + } | null; + /** + * @description discriminator enum property added by openapi-typescript + * @enum {string} + */ + kind: 'openhands__tools__gemini__write_file__definition__WriteFileTool-Output__1'; + /** Title */ + readonly title: string; + }; + /** + * Tool + * @description Definition for a tool the client can call. + */ + mcp__types__Tool: { + /** Name */ + name: string; + /** Title */ + title?: string | null; + /** Description */ + description?: string | null; + /** Inputschema */ + inputSchema: { + [key: string]: unknown; + }; + /** Outputschema */ + outputSchema?: { + [key: string]: unknown; + } | null; + /** Icons */ + icons?: components['schemas']['Icon'][] | null; + annotations?: components['schemas']['mcp__types__ToolAnnotations'] | null; + /** Meta */ + _meta?: { + [key: string]: unknown; + } | null; + execution?: components['schemas']['ToolExecution'] | null; + } & { + [key: string]: unknown; + }; + /** + * ToolAnnotations + * @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. + */ + mcp__types__ToolAnnotations: { + /** Title */ + title?: string | null; + /** Readonlyhint */ + readOnlyHint?: boolean | null; + /** Destructivehint */ + destructiveHint?: boolean | null; + /** Idempotenthint */ + idempotentHint?: boolean | null; + /** Openworldhint */ + openWorldHint?: boolean | null; + } & { + [key: string]: unknown; + }; + /** + * Tool + * @description Defines a tool to be initialized for the agent. + * + * This is only used in agent-sdk for type schema for server use. + */ + openhands__sdk__tool__spec__Tool: { + /** + * Name + * @description Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage. + * @example TerminalTool + * @example FileEditorTool + * @example TaskTrackerTool + */ + name: string; + /** + * Params + * @description Parameters for the tool's .create() method, e.g., {'working_dir': '/app'} + * @example { + * "working_dir": "/workspace" + * } + */ + params?: { + [key: string]: unknown; + }; + }; + /** + * 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 + */ + openhands__sdk__tool__tool__ToolAnnotations: { + /** + * Title + * @description A human-readable title for the tool. + */ + title?: string | null; + /** + * Readonlyhint + * @description If true, the tool does not modify its environment. Default: false + * @default false + */ + readOnlyHint?: boolean; + /** + * Destructivehint + * @description If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. (This property is meaningful only when `readOnlyHint == false`) Default: true + * @default true + */ + destructiveHint?: boolean; + /** + * Idempotenthint + * @description If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment. (This property is meaningful only when `readOnlyHint == false`) Default: false + * @default false + */ + idempotentHint?: boolean; + /** + * Openworldhint + * @description If true, this tool may interact with an 'open world' of external entities. If false, the tool's domain of interaction is closed. For example, the world of a web search tool is open, whereas that of a memory tool is not. Default: true + * @default true + */ + openWorldHint?: boolean; + }; + }; + responses: never; + parameters: never; + requestBodies: never; + headers: never; + pathItems: never; +}; +export type AcpAgentInput = components['schemas']['ACPAgent-Input']; +export type AcpAgentOutput = components['schemas']['ACPAgent-Output']; +export type AcpToolCallEvent = components['schemas']['ACPToolCallEvent']; +export type ApiBasedCriticInput = components['schemas']['APIBasedCritic-Input']; +export type ApiBasedCriticOutput = components['schemas']['APIBasedCritic-Output']; +export type Action = components['schemas']['Action']; +export type ActionEvent = components['schemas']['ActionEvent']; +export type ActivateProfileResponse = components['schemas']['ActivateProfileResponse']; +export type AgentInput = components['schemas']['Agent-Input']; +export type AgentOutput = components['schemas']['Agent-Output']; +export type AgentBaseInput = components['schemas']['AgentBase-Input']; +export type AgentBaseOutput = components['schemas']['AgentBase-Output']; +export type AgentContextInput = components['schemas']['AgentContext-Input']; +export type AgentContextOutput = components['schemas']['AgentContext-Output']; +export type AgentDefinition = components['schemas']['AgentDefinition']; +export type AgentErrorEvent = components['schemas']['AgentErrorEvent']; +export type AgentFinishedCriticInput = components['schemas']['AgentFinishedCritic-Input']; +export type AgentFinishedCriticOutput = components['schemas']['AgentFinishedCritic-Output']; +export type AgentResponseResult = components['schemas']['AgentResponseResult']; +export type AlwaysConfirmInput = components['schemas']['AlwaysConfirm-Input']; +export type AlwaysConfirmOutput = components['schemas']['AlwaysConfirm-Output']; +export type AskAgentRequest = components['schemas']['AskAgentRequest']; +export type AskAgentResponse = components['schemas']['AskAgentResponse']; +export type BaseWorkspace = components['schemas']['BaseWorkspace']; +export type BashCommand = components['schemas']['BashCommand']; +export type BashError = components['schemas']['BashError']; +export type BashEventBase = components['schemas']['BashEventBase']; +export type BashEventPage = components['schemas']['BashEventPage']; +export type BashEventSortOrder = components['schemas']['BashEventSortOrder']; +export type BashOutput = components['schemas']['BashOutput']; +export type BodySwitchConversationLlmApiConversationsConversationIdSwitchLlmPost = + components['schemas']['Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post']; +export type BodySwitchConversationProfileApiConversationsConversationIdSwitchProfilePost = + components['schemas']['Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post']; +export type BodyUploadFileQueryApiFileUploadPost = + components['schemas']['Body_upload_file_query_api_file_upload_post']; +export type BrowserAction = components['schemas']['BrowserAction']; +export type BrowserActionWithRisk = components['schemas']['BrowserActionWithRisk']; +export type BrowserClickAction = components['schemas']['BrowserClickAction']; +export type BrowserClickActionWithRisk = components['schemas']['BrowserClickActionWithRisk']; +export type BrowserClickTool = components['schemas']['BrowserClickTool']; +export type BrowserCloseTabAction = components['schemas']['BrowserCloseTabAction']; +export type BrowserCloseTabActionWithRisk = components['schemas']['BrowserCloseTabActionWithRisk']; +export type BrowserCloseTabTool = components['schemas']['BrowserCloseTabTool']; +export type BrowserGetContentAction = components['schemas']['BrowserGetContentAction']; +export type BrowserGetContentActionWithRisk = + components['schemas']['BrowserGetContentActionWithRisk']; +export type BrowserGetContentTool = components['schemas']['BrowserGetContentTool']; +export type BrowserGetStateAction = components['schemas']['BrowserGetStateAction']; +export type BrowserGetStateActionWithRisk = components['schemas']['BrowserGetStateActionWithRisk']; +export type BrowserGetStateTool = components['schemas']['BrowserGetStateTool']; +export type BrowserGetStorageAction = components['schemas']['BrowserGetStorageAction']; +export type BrowserGetStorageActionWithRisk = + components['schemas']['BrowserGetStorageActionWithRisk']; +export type BrowserGetStorageTool = components['schemas']['BrowserGetStorageTool']; +export type BrowserGoBackAction = components['schemas']['BrowserGoBackAction']; +export type BrowserGoBackActionWithRisk = components['schemas']['BrowserGoBackActionWithRisk']; +export type BrowserGoBackTool = components['schemas']['BrowserGoBackTool']; +export type BrowserListTabsAction = components['schemas']['BrowserListTabsAction']; +export type BrowserListTabsActionWithRisk = components['schemas']['BrowserListTabsActionWithRisk']; +export type BrowserListTabsTool = components['schemas']['BrowserListTabsTool']; +export type BrowserNavigateAction = components['schemas']['BrowserNavigateAction']; +export type BrowserNavigateActionWithRisk = components['schemas']['BrowserNavigateActionWithRisk']; +export type BrowserNavigateTool = components['schemas']['BrowserNavigateTool']; +export type BrowserObservation = components['schemas']['BrowserObservation']; +export type BrowserScrollAction = components['schemas']['BrowserScrollAction']; +export type BrowserScrollActionWithRisk = components['schemas']['BrowserScrollActionWithRisk']; +export type BrowserScrollTool = components['schemas']['BrowserScrollTool']; +export type BrowserSetStorageAction = components['schemas']['BrowserSetStorageAction']; +export type BrowserSetStorageActionWithRisk = + components['schemas']['BrowserSetStorageActionWithRisk']; +export type BrowserSetStorageTool = components['schemas']['BrowserSetStorageTool']; +export type BrowserStartRecordingAction = components['schemas']['BrowserStartRecordingAction']; +export type BrowserStartRecordingActionWithRisk = + components['schemas']['BrowserStartRecordingActionWithRisk']; +export type BrowserStartRecordingTool = components['schemas']['BrowserStartRecordingTool']; +export type BrowserStopRecordingAction = components['schemas']['BrowserStopRecordingAction']; +export type BrowserStopRecordingActionWithRisk = + components['schemas']['BrowserStopRecordingActionWithRisk']; +export type BrowserStopRecordingTool = components['schemas']['BrowserStopRecordingTool']; +export type BrowserSwitchTabAction = components['schemas']['BrowserSwitchTabAction']; +export type BrowserSwitchTabActionWithRisk = + components['schemas']['BrowserSwitchTabActionWithRisk']; +export type BrowserSwitchTabTool = components['schemas']['BrowserSwitchTabTool']; +export type BrowserToolSet = components['schemas']['BrowserToolSet']; +export type BrowserTypeAction = components['schemas']['BrowserTypeAction']; +export type BrowserTypeActionWithRisk = components['schemas']['BrowserTypeActionWithRisk']; +export type BrowserTypeTool = components['schemas']['BrowserTypeTool']; +export type CloudProxyRequest = components['schemas']['CloudProxyRequest']; +export type CmdOutputMetadata = components['schemas']['CmdOutputMetadata']; +export type Condensation = components['schemas']['Condensation']; +export type CondensationRequest = components['schemas']['CondensationRequest']; +export type CondensationSummaryEvent = components['schemas']['CondensationSummaryEvent']; +export type CondenserBaseInput = components['schemas']['CondenserBase-Input']; +export type CondenserBaseOutput = components['schemas']['CondenserBase-Output']; +export type ConfirmRiskyInput = components['schemas']['ConfirmRisky-Input']; +export type ConfirmRiskyOutput = components['schemas']['ConfirmRisky-Output']; +export type ConfirmationPolicyBaseInput = components['schemas']['ConfirmationPolicyBase-Input']; +export type ConfirmationPolicyBaseOutput = components['schemas']['ConfirmationPolicyBase-Output']; +export type ConfirmationResponseRequest = components['schemas']['ConfirmationResponseRequest']; +export type ConversationErrorEvent = components['schemas']['ConversationErrorEvent']; +export type ConversationExecutionStatus = components['schemas']['ConversationExecutionStatus']; +export type ConversationInfo = components['schemas']['ConversationInfo']; +export type ConversationPage = components['schemas']['ConversationPage']; +export type ConversationSortOrder = components['schemas']['ConversationSortOrder']; +export type ConversationStateUpdateEvent = components['schemas']['ConversationStateUpdateEvent']; +export type ConversationStats = components['schemas']['ConversationStats']; +export type Cost = components['schemas']['Cost']; +export type CriticBaseInput = components['schemas']['CriticBase-Input']; +export type CriticBaseOutput = components['schemas']['CriticBase-Output']; +export type CriticResult = components['schemas']['CriticResult']; +export type DelegateAction = components['schemas']['DelegateAction']; +export type DelegateActionWithRisk = components['schemas']['DelegateActionWithRisk']; +export type DelegateObservation = components['schemas']['DelegateObservation']; +export type DelegateTool = components['schemas']['DelegateTool']; +export type DesktopUrlResponse = components['schemas']['DesktopUrlResponse']; +export type EditAction = components['schemas']['EditAction']; +export type EditActionWithRisk = components['schemas']['EditActionWithRisk']; +export type EditObservation = components['schemas']['EditObservation']; +export type EditTool = components['schemas']['EditTool']; +export type EmptyPatchCriticInput = components['schemas']['EmptyPatchCritic-Input']; +export type EmptyPatchCriticOutput = components['schemas']['EmptyPatchCritic-Output']; +export type EnsembleSecurityAnalyzerInput = components['schemas']['EnsembleSecurityAnalyzer-Input']; +export type EnsembleSecurityAnalyzerOutput = + components['schemas']['EnsembleSecurityAnalyzer-Output']; +export type Event = components['schemas']['Event']; +export type EventPage = components['schemas']['EventPage']; +export type EventSortOrder = components['schemas']['EventSortOrder']; +export type ExecuteBashRequest = components['schemas']['ExecuteBashRequest']; +export type ExposedUrl = components['schemas']['ExposedUrl']; +export type FallbackStrategy = components['schemas']['FallbackStrategy']; +export type FileBrowserEntry = components['schemas']['FileBrowserEntry']; +export type FileEditorAction = components['schemas']['FileEditorAction']; +export type FileEditorActionWithRisk = components['schemas']['FileEditorActionWithRisk']; +export type FileEditorObservation = components['schemas']['FileEditorObservation']; +export type FileEditorTool = components['schemas']['FileEditorTool']; +export type FileEntry = components['schemas']['FileEntry']; +export type FinishAction = components['schemas']['FinishAction']; +export type FinishActionWithRisk = components['schemas']['FinishActionWithRisk']; +export type FinishObservation = components['schemas']['FinishObservation']; +export type FinishTool = components['schemas']['FinishTool']; +export type ForkConversationRequest = components['schemas']['ForkConversationRequest']; +export type GitChange = components['schemas']['GitChange']; +export type GitChangeStatus = components['schemas']['GitChangeStatus']; +export type GitDiff = components['schemas']['GitDiff']; +export type GlobAction = components['schemas']['GlobAction']; +export type GlobActionWithRisk = components['schemas']['GlobActionWithRisk']; +export type GlobObservation = components['schemas']['GlobObservation']; +export type GlobTool = components['schemas']['GlobTool']; +export type GraySwanAnalyzerInput = components['schemas']['GraySwanAnalyzer-Input']; +export type GraySwanAnalyzerOutput = components['schemas']['GraySwanAnalyzer-Output']; +export type GrepAction = components['schemas']['GrepAction']; +export type GrepActionWithRisk = components['schemas']['GrepActionWithRisk']; +export type GrepObservation = components['schemas']['GrepObservation']; +export type GrepTool = components['schemas']['GrepTool']; +export type HttpValidationError = components['schemas']['HTTPValidationError']; +export type HealthStatus = components['schemas']['HealthStatus']; +export type HomeResponse = components['schemas']['HomeResponse']; +export type HookConfigInput = components['schemas']['HookConfig-Input']; +export type HookConfigOutput = components['schemas']['HookConfig-Output']; +export type HookDefinition = components['schemas']['HookDefinition']; +export type HookExecutionEvent = components['schemas']['HookExecutionEvent']; +export type HookMatcherInput = components['schemas']['HookMatcher-Input']; +export type HookMatcherOutput = components['schemas']['HookMatcher-Output']; +export type HookType = components['schemas']['HookType']; +export type HooksRequest = components['schemas']['HooksRequest']; +export type HooksResponse = components['schemas']['HooksResponse']; +export type Icon = components['schemas']['Icon']; +export type ImageContent = components['schemas']['ImageContent']; +export type InputMetadata = components['schemas']['InputMetadata']; +export type InvokeSkillAction = components['schemas']['InvokeSkillAction']; +export type InvokeSkillActionWithRisk = components['schemas']['InvokeSkillActionWithRisk']; +export type InvokeSkillObservation = components['schemas']['InvokeSkillObservation']; +export type InvokeSkillTool = components['schemas']['InvokeSkillTool']; +export type IterativeRefinementConfig = components['schemas']['IterativeRefinementConfig']; +export type KeywordTrigger = components['schemas']['KeywordTrigger']; +export type LlmInput = components['schemas']['LLM-Input']; +export type LlmOutput = components['schemas']['LLM-Output']; +export type LlmCompletionLogEvent = components['schemas']['LLMCompletionLogEvent']; +export type LlmSecurityAnalyzerInput = components['schemas']['LLMSecurityAnalyzer-Input']; +export type LlmSecurityAnalyzerOutput = components['schemas']['LLMSecurityAnalyzer-Output']; +export type LlmSummarizingCondenserInput = components['schemas']['LLMSummarizingCondenser-Input']; +export type LlmSummarizingCondenserOutput = components['schemas']['LLMSummarizingCondenser-Output']; +export type ListDirectoryAction = components['schemas']['ListDirectoryAction']; +export type ListDirectoryActionWithRisk = components['schemas']['ListDirectoryActionWithRisk']; +export type ListDirectoryObservation = components['schemas']['ListDirectoryObservation']; +export type ListDirectoryTool = components['schemas']['ListDirectoryTool']; +export type LocalWorkspaceInput = components['schemas']['LocalWorkspace-Input']; +export type LocalWorkspaceOutput = components['schemas']['LocalWorkspace-Output']; +export type LookupSecretInput = components['schemas']['LookupSecret-Input']; +export type LookupSecretOutput = components['schemas']['LookupSecret-Output']; +export type McpToolAction = components['schemas']['MCPToolAction']; +export type McpToolActionWithRisk = components['schemas']['MCPToolActionWithRisk']; +export type McpToolDefinition = components['schemas']['MCPToolDefinition']; +export type McpToolObservation = components['schemas']['MCPToolObservation']; +export type Message = components['schemas']['Message']; +export type MessageEvent = components['schemas']['MessageEvent']; +export type MessageToolCall = components['schemas']['MessageToolCall']; +export type Metrics = components['schemas']['Metrics']; +export type MetricsSnapshot = components['schemas']['MetricsSnapshot']; +export type ModelsResponse = components['schemas']['ModelsResponse']; +export type NeverConfirmInput = components['schemas']['NeverConfirm-Input']; +export type NeverConfirmOutput = components['schemas']['NeverConfirm-Output']; +export type NoOpCondenserInput = components['schemas']['NoOpCondenser-Input']; +export type NoOpCondenserOutput = components['schemas']['NoOpCondenser-Output']; +export type Observation = components['schemas']['Observation']; +export type ObservationEvent = components['schemas']['ObservationEvent']; +export type OrgConfig = components['schemas']['OrgConfig']; +export type PassCriticInput = components['schemas']['PassCritic-Input']; +export type PassCriticOutput = components['schemas']['PassCritic-Output']; +export type PatternSecurityAnalyzerInput = components['schemas']['PatternSecurityAnalyzer-Input']; +export type PatternSecurityAnalyzerOutput = components['schemas']['PatternSecurityAnalyzer-Output']; +export type PauseEvent = components['schemas']['PauseEvent']; +export type PipelineCondenserInput = components['schemas']['PipelineCondenser-Input']; +export type PipelineCondenserOutput = components['schemas']['PipelineCondenser-Output']; +export type PlanningFileEditorAction = components['schemas']['PlanningFileEditorAction']; +export type PlanningFileEditorActionWithRisk = + components['schemas']['PlanningFileEditorActionWithRisk']; +export type PlanningFileEditorObservation = components['schemas']['PlanningFileEditorObservation']; +export type PlanningFileEditorTool = components['schemas']['PlanningFileEditorTool']; +export type PluginSource = components['schemas']['PluginSource']; +export type PolicyRailSecurityAnalyzerInput = + components['schemas']['PolicyRailSecurityAnalyzer-Input']; +export type PolicyRailSecurityAnalyzerOutput = + components['schemas']['PolicyRailSecurityAnalyzer-Output']; +export type ProfileDetailResponse = components['schemas']['ProfileDetailResponse']; +export type ProfileInfo = components['schemas']['ProfileInfo']; +export type ProfileListResponse = components['schemas']['ProfileListResponse']; +export type ProfileMutationResponse = components['schemas']['ProfileMutationResponse']; +export type ProvidersResponse = components['schemas']['ProvidersResponse']; +export type ReadFileAction = components['schemas']['ReadFileAction']; +export type ReadFileActionWithRisk = components['schemas']['ReadFileActionWithRisk']; +export type ReadFileObservation = components['schemas']['ReadFileObservation']; +export type ReadFileTool = components['schemas']['ReadFileTool']; +export type ReasoningItemModel = components['schemas']['ReasoningItemModel']; +export type RedactedThinkingBlock = components['schemas']['RedactedThinkingBlock']; +export type RemoteWorkspace = components['schemas']['RemoteWorkspace']; +export type RenameProfileRequest = components['schemas']['RenameProfileRequest']; +export type ResponseLatency = components['schemas']['ResponseLatency']; +export type SandboxConfig = components['schemas']['SandboxConfig']; +export type SaveProfileRequest = components['schemas']['SaveProfileRequest']; +export type SecretCreateRequest = components['schemas']['SecretCreateRequest']; +export type SecretItemResponse = components['schemas']['SecretItemResponse']; +export type SecretRegistry = components['schemas']['SecretRegistry']; +export type SecretSourceInput = components['schemas']['SecretSource-Input']; +export type SecretSourceOutput = components['schemas']['SecretSource-Output']; +export type SecretsListResponse = components['schemas']['SecretsListResponse']; +export type SecurityAnalyzerBaseInput = components['schemas']['SecurityAnalyzerBase-Input']; +export type SecurityAnalyzerBaseOutput = components['schemas']['SecurityAnalyzerBase-Output']; +export type SecurityRisk = components['schemas']['SecurityRisk']; +export type SendMessageRequest = components['schemas']['SendMessageRequest']; +export type ServerErrorEvent = components['schemas']['ServerErrorEvent']; +export type ServerInfo = components['schemas']['ServerInfo']; +export type SetConfirmationPolicyRequest = components['schemas']['SetConfirmationPolicyRequest']; +export type SetSecurityAnalyzerRequest = components['schemas']['SetSecurityAnalyzerRequest']; +export type SettingProminence = components['schemas']['SettingProminence']; +export type SettingsChoice = components['schemas']['SettingsChoice']; +export type SettingsFieldSchema = components['schemas']['SettingsFieldSchema']; +export type SettingsResponse = components['schemas']['SettingsResponse']; +export type SettingsSchema = components['schemas']['SettingsSchema']; +export type SettingsSectionSchema = components['schemas']['SettingsSectionSchema']; +export type SettingsUpdateRequest = components['schemas']['SettingsUpdateRequest']; +export type Skill = components['schemas']['Skill']; +export type SkillInfo = components['schemas']['SkillInfo']; +export type SkillResources = components['schemas']['SkillResources']; +export type SkillsRequest = components['schemas']['SkillsRequest']; +export type SkillsResponse = components['schemas']['SkillsResponse']; +export type StartAcpConversationRequest = components['schemas']['StartACPConversationRequest']; +export type StartConversationRequest = components['schemas']['StartConversationRequest']; +export type StaticSecretInput = components['schemas']['StaticSecret-Input']; +export type StaticSecretOutput = components['schemas']['StaticSecret-Output']; +export type StreamingDeltaEvent = components['schemas']['StreamingDeltaEvent']; +export type SubdirectoryEntry = components['schemas']['SubdirectoryEntry']; +export type SubdirectoryPage = components['schemas']['SubdirectoryPage']; +export type Success = components['schemas']['Success']; +export type SwitchLlmAction = components['schemas']['SwitchLLMAction']; +export type SwitchLlmActionWithRisk = components['schemas']['SwitchLLMActionWithRisk']; +export type SwitchLlmObservation = components['schemas']['SwitchLLMObservation']; +export type SwitchLlmTool = components['schemas']['SwitchLLMTool']; +export type SyncResponse = components['schemas']['SyncResponse']; +export type SystemPromptEvent = components['schemas']['SystemPromptEvent']; +export type TaskAction = components['schemas']['TaskAction']; +export type TaskActionWithRisk = components['schemas']['TaskActionWithRisk']; +export type TaskItem = components['schemas']['TaskItem']; +export type TaskObservation = components['schemas']['TaskObservation']; +export type TaskTool = components['schemas']['TaskTool']; +export type TaskToolSet = components['schemas']['TaskToolSet']; +export type TaskTrackerAction = components['schemas']['TaskTrackerAction']; +export type TaskTrackerActionWithRisk = components['schemas']['TaskTrackerActionWithRisk']; +export type TaskTrackerObservation = components['schemas']['TaskTrackerObservation']; +export type TaskTrackerTool = components['schemas']['TaskTrackerTool']; +export type TaskTrigger = components['schemas']['TaskTrigger']; +export type TerminalAction = components['schemas']['TerminalAction']; +export type TerminalActionWithRisk = components['schemas']['TerminalActionWithRisk']; +export type TerminalObservation = components['schemas']['TerminalObservation']; +export type TerminalTool = components['schemas']['TerminalTool']; +export type TextContent = components['schemas']['TextContent']; +export type ThinkAction = components['schemas']['ThinkAction']; +export type ThinkActionWithRisk = components['schemas']['ThinkActionWithRisk']; +export type ThinkObservation = components['schemas']['ThinkObservation']; +export type ThinkTool = components['schemas']['ThinkTool']; +export type ThinkingBlock = components['schemas']['ThinkingBlock']; +export type TokenEvent = components['schemas']['TokenEvent']; +export type TokenUsage = components['schemas']['TokenUsage']; +export type ToolInput = components['schemas']['Tool-Input']; +export type ToolDefinition = components['schemas']['ToolDefinition']; +export type ToolExecution = components['schemas']['ToolExecution']; +export type UpdateConversationRequest = components['schemas']['UpdateConversationRequest']; +export type UpdateSecretsRequest = components['schemas']['UpdateSecretsRequest']; +export type UserRejectObservation = components['schemas']['UserRejectObservation']; +export type VsCodeUrlResponse = components['schemas']['VSCodeUrlResponse']; +export type ValidationError = components['schemas']['ValidationError']; +export type VerifiedModelsResponse = components['schemas']['VerifiedModelsResponse']; +export type WriteFileAction = components['schemas']['WriteFileAction']; +export type WriteFileActionWithRisk = components['schemas']['WriteFileActionWithRisk']; +export type WriteFileObservation = components['schemas']['WriteFileObservation']; +export type WriteFileTool = components['schemas']['WriteFileTool']; +export type McpTypesTool = components['schemas']['mcp__types__Tool']; +export type McpTypesToolAnnotations = components['schemas']['mcp__types__ToolAnnotations']; +export type OpenhandsSdkToolSpecTool = components['schemas']['openhands__sdk__tool__spec__Tool']; +export type OpenhandsSdkToolToolToolAnnotations = + components['schemas']['openhands__sdk__tool__tool__ToolAnnotations']; +export type $defs = Record; +export interface operations { + alive_alive_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HealthStatus']; + }; + }; + }; + }; + health_health_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HealthStatus']; + }; + }; + }; + }; + ready_ready_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': { + [key: string]: string; + }; + }; + }; + }; + }; + get_server_info_server_info_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ServerInfo']; + }; + }; + }; + }; + search_conversation_events_api_conversations__conversation_id__events_search_get: { + parameters: { + query?: { + page_id?: string | null; + limit?: number; + kind?: string | null; + source?: string | null; + body?: string | null; + sort_order?: components['schemas']['EventSortOrder']; + timestamp__gte?: string | null; + timestamp__lt?: string | null; + }; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['EventPage']; + }; + }; + /** @description Conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + count_conversation_events_api_conversations__conversation_id__events_count_get: { + parameters: { + query?: { + kind?: string | null; + source?: string | null; + body?: string | null; + timestamp__gte?: string | null; + timestamp__lt?: string | null; + }; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': number; + }; + }; + /** @description Conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_conversation_event_api_conversations__conversation_id__events__event_id__get: { + parameters: { + query?: never; + header?: never; + path: { + event_id: string; + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Event']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + batch_get_conversation_events_api_conversations__conversation_id__events_get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': string[]; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': (components['schemas']['Event'] | null)[]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + send_message_api_conversations__conversation_id__events_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SendMessageRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + respond_to_confirmation_api_conversations__conversation_id__events_respond_to_confirmation_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['ConfirmationResponseRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + search_conversations_api_conversations_search_get: { + parameters: { + query?: { + page_id?: string | null; + limit?: number; + status?: components['schemas']['ConversationExecutionStatus'] | null; + sort_order?: components['schemas']['ConversationSortOrder']; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationPage']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + count_conversations_api_conversations_count_get: { + parameters: { + query?: { + status?: components['schemas']['ConversationExecutionStatus'] | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': number; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_conversation_api_conversations__conversation_id__get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationInfo']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + delete_conversation_api_conversations__conversation_id__delete: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + update_conversation_api_conversations__conversation_id__patch: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['UpdateConversationRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_conversation_agent_final_response_api_conversations__conversation_id__agent_final_response_get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['AgentResponseResult']; + }; + }; + /** @description Conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + batch_get_conversations_api_conversations_get: { + parameters: { + query: { + ids: string[]; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': (components['schemas']['ConversationInfo'] | null)[]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + start_conversation_api_conversations_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['StartConversationRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationInfo']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + pause_conversation_api_conversations__conversation_id__pause_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + run_conversation_api_conversations__conversation_id__run_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Conversation is already running */ + 409: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + update_conversation_secrets_api_conversations__conversation_id__secrets_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['UpdateSecretsRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + set_conversation_confirmation_policy_api_conversations__conversation_id__confirmation_policy_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SetConfirmationPolicyRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + set_conversation_security_analyzer_api_conversations__conversation_id__security_analyzer_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SetSecurityAnalyzerRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + switch_conversation_profile_api_conversations__conversation_id__switch_profile_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Invalid or corrupted profile */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Conversation or profile not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + switch_conversation_llm_api_conversations__conversation_id__switch_llm_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + ask_agent_api_conversations__conversation_id__ask_agent_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['AskAgentRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['AskAgentResponse']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + condense_conversation_api_conversations__conversation_id__condense_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + fork_conversation_api_conversations__conversation_id__fork_post: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: { + content: { + 'application/json': components['schemas']['ForkConversationRequest']; + }; + }; + responses: { + /** @description Forked conversation created */ + 201: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationInfo']; + }; + }; + /** @description Source conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Fork ID already in use */ + 409: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + search_acp_conversations_api_acp_conversations_search_get: { + parameters: { + query?: { + page_id?: string | null; + limit?: number; + status?: components['schemas']['ConversationExecutionStatus'] | null; + sort_order?: components['schemas']['ConversationSortOrder']; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationPage']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + count_acp_conversations_api_acp_conversations_count_get: { + parameters: { + query?: { + status?: components['schemas']['ConversationExecutionStatus'] | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': number; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_acp_conversation_api_acp_conversations__conversation_id__get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationInfo']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + batch_get_acp_conversations_api_acp_conversations_get: { + parameters: { + query: { + ids: string[]; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': (components['schemas']['ConversationInfo'] | null)[]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + start_acp_conversation_api_acp_conversations_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['StartACPConversationRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ConversationInfo']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + list_available_tools_api_tools__get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': string[]; + }; + }; + }; + }; + search_bash_events_api_bash_bash_events_search_get: { + parameters: { + query?: { + kind__eq?: ('BashCommand' | 'BashOutput') | null; + command_id__eq?: string | null; + timestamp__gte?: string | null; + timestamp__lt?: string | null; + /** @description Only returns BashOutput events with order > this value. Useful for polling to fetch only new events since the last poll. */ + order__gt?: number | null; + sort_order?: components['schemas']['BashEventSortOrder']; + page_id?: string | null; + limit?: number; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['BashEventPage']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_bash_event_api_bash_bash_events__event_id__get: { + parameters: { + query?: never; + header?: never; + path: { + event_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['BashEventBase']; + }; + }; + /** @description Item not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + batch_get_bash_events_api_bash_bash_events__get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': string[]; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': (components['schemas']['BashEventBase'] | null)[]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + start_bash_command_api_bash_start_bash_command_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['ExecuteBashRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['BashCommand']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + execute_bash_command_api_bash_execute_bash_command_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['ExecuteBashRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['BashOutput']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + clear_all_bash_events_api_bash_bash_events_delete: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': { + [key: string]: number; + }; + }; + }; + }; + }; + git_changes_query_api_git_changes_get: { + parameters: { + query: { + /** @description The git repository path */ + path: string; + /** @description Optional git ref to diff against (e.g. 'HEAD' for git status-style changes, or a commit hash). When omitted, the upstream/default branch is auto-detected. */ + ref?: string | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['GitChange'][]; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + git_diff_query_api_git_diff_get: { + parameters: { + query: { + /** @description The file path to get diff for */ + path: string; + /** @description Optional git ref to diff against (e.g. 'HEAD' for git status-style changes, or a commit hash). When omitted, the upstream/default branch is auto-detected. */ + ref?: string | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['GitDiff']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + upload_file_query_api_file_upload_post: { + parameters: { + query: { + /** @description Absolute file path */ + path: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'multipart/form-data': components['schemas']['Body_upload_file_query_api_file_upload_post']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['Success']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + download_file_query_api_file_download_get: { + parameters: { + query: { + /** @description Absolute file path */ + path: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_home_directory_api_file_home_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HomeResponse']; + }; + }; + }; + }; + search_subdirs_api_file_search_subdirs_get: { + parameters: { + query: { + /** @description Absolute directory path to list subdirectories of */ + path: string; + page_id?: string | null; + limit?: number; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SubdirectoryPage']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + download_trajectory_api_file_download_trajectory__conversation_id__get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_vscode_url_api_vscode_url_get: { + parameters: { + query?: { + base_url?: string; + workspace_dir?: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['VSCodeUrlResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_vscode_status_api_vscode_status_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': { + [key: string]: boolean | string; + }; + }; + }; + }; + }; + get_desktop_url_api_desktop_url_get: { + parameters: { + query?: { + base_url?: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['DesktopUrlResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_skills_api_skills_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SkillsRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SkillsResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + sync_skills_api_skills_sync_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SyncResponse']; + }; + }; + }; + }; + get_hooks_api_hooks_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['HooksRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HooksResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + list_providers_api_llm_providers_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ProvidersResponse']; + }; + }; + }; + }; + list_models_api_llm_models_get: { + parameters: { + query?: { + /** @description Filter models by provider (e.g., 'openai', 'anthropic') */ + provider?: string | null; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ModelsResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + list_verified_models_api_llm_models_verified_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['VerifiedModelsResponse']; + }; + }; + }; + }; + get_agent_settings_schema_api_settings_agent_schema_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SettingsSchema']; + }; + }; + }; + }; + get_conversation_settings_schema_api_settings_conversation_schema_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SettingsSchema']; + }; + }; + }; + }; + get_settings_api_settings_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SettingsResponse']; + }; + }; + }; + }; + update_settings_api_settings_patch: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SettingsUpdateRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SettingsResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + list_secrets_api_settings_secrets_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SecretsListResponse']; + }; + }; + }; + }; + create_secret_api_settings_secrets_put: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SecretCreateRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['SecretItemResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_secret_value_api_settings_secrets__name__get: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + delete_secret_api_settings_secrets__name__delete: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': { + [key: string]: boolean; + }; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + list_profiles_api_profiles_get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ProfileListResponse']; + }; + }; + }; + }; + get_profile_api_profiles__name__get: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ProfileDetailResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + save_profile_api_profiles__name__post: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['SaveProfileRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 201: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ProfileMutationResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + delete_profile_api_profiles__name__delete: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ProfileMutationResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + rename_profile_api_profiles__name__rename_post: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['RenameProfileRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ProfileMutationResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + activate_profile_api_profiles__name__activate_post: { + parameters: { + query?: never; + header?: never; + path: { + name: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ActivateProfileResponse']; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + cloud_proxy_api_cloud_proxy_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody: { + content: { + 'application/json': components['schemas']['CloudProxyRequest']; + }; + }; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + create_workspace_session_api_auth_workspace_session_post: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Cookie set */ + 204: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Missing or invalid X-Session-API-Key header */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + delete_workspace_session_api_auth_workspace_session_delete: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Cookie cleared */ + 204: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + serve_workspace_root_api_conversations__conversation_id__workspace_get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description File or conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + serve_workspace_file_api_conversations__conversation_id__workspace__file_path__get: { + parameters: { + query?: never; + header?: never; + path: { + conversation_id: string; + file_path: string; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': unknown; + }; + }; + /** @description File or conversation not found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Validation Error */ + 422: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['HTTPValidationError']; + }; + }; + }; + }; + get_server_info__get: { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Successful Response */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['ServerInfo']; + }; + }; + }; + }; +} diff --git a/src/index.ts b/src/index.ts index d697a78..aa94a87 100644 --- a/src/index.ts +++ b/src/index.ts @@ -163,6 +163,20 @@ export type { export type { AgentOptions } from './agent/agent'; +// Generated Agent Server OpenAPI request/response models. +export type { + paths as AgentServerPaths, + components as AgentServerComponents, + operations as AgentServerOperations, + StartConversationRequest, + StartAcpConversationRequest as StartACPConversationRequest, + ConversationInfo as AgentServerConversationInfo, + ConversationPage, + SettingsResponse, + LocalWorkspaceInput, + AgentBaseInput, +} from './generated/agent-server-api'; + export { EventSortOrder, AgentExecutionStatus, ConversationExecutionStatus } from './types/base'; export { ConversationSortOrder } from './models/conversation'; diff --git a/src/models/api.ts b/src/models/api.ts index b699ddc..9a3d018 100644 --- a/src/models/api.ts +++ b/src/models/api.ts @@ -3,6 +3,11 @@ */ import { LLM } from '../types/base'; +import type { + SettingsResponse as GeneratedSettingsResponse, + SettingsSchema as GeneratedSettingsSchema, + SettingsUpdateRequest as GeneratedSettingsUpdateRequest, +} from '../generated/agent-server-api'; export interface AliveStatus { status: string; @@ -25,10 +30,7 @@ export interface VerifiedModelsResponse { models: Record; } -export interface SettingsSchema { - model_name: string; - sections: Array>; -} +export type SettingsSchema = GeneratedSettingsSchema; export interface ExposedUrl { name: string; @@ -134,18 +136,9 @@ export type ExposeSecretsMode = 'encrypted' | 'plaintext'; export type SettingsValue = unknown; -export interface SettingsApiResponse { - agent_settings: Record; - conversation_settings: Record; - llm_api_key_is_set: boolean; - [key: string]: unknown; -} +export type SettingsApiResponse = GeneratedSettingsResponse; -export interface SettingsUpdateRequest { - agent_settings_diff?: Record; - conversation_settings_diff?: Record; - [key: string]: unknown; -} +export type SettingsUpdateRequest = GeneratedSettingsUpdateRequest; export interface SecretInfo { name: string; diff --git a/swagger-doc.json b/swagger-doc.json index c64efc2..fb423fc 100644 --- a/swagger-doc.json +++ b/swagger-doc.json @@ -8,17 +8,18 @@ "paths": { "/alive": { "get": { - "tags": [ - "Server Details" - ], + "tags": ["Server Details"], "summary": "Alive", + "description": "Basic liveness check - returns OK if the server process is running.", "operationId": "alive_alive_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { - "schema": {} + "schema": { + "$ref": "#/components/schemas/HealthStatus" + } } } } @@ -27,10 +28,9 @@ }, "/health": { "get": { - "tags": [ - "Server Details" - ], + "tags": ["Server Details"], "summary": "Health", + "description": "Basic health check - returns OK if the server process is running.", "operationId": "health_health_get", "responses": { "200": { @@ -38,8 +38,31 @@ "content": { "application/json": { "schema": { - "type": "string", - "title": "Response Health Health Get" + "$ref": "#/components/schemas/HealthStatus" + } + } + } + } + } + } + }, + "/ready": { + "get": { + "tags": ["Server Details"], + "summary": "Ready", + "description": "Readiness check - returns OK only if the server has completed initialization.\n\nThis endpoint should be used by Kubernetes readiness probes to determine\nwhen the pod is ready to receive traffic. Returns 503 during initialization.", + "operationId": "ready_ready_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Response Ready Ready Get" } } } @@ -49,9 +72,7 @@ }, "/server_info": { "get": { - "tags": [ - "Server Details" - ], + "tags": ["Server Details"], "summary": "Get Server Info", "operationId": "get_server_info_server_info_get", "responses": { @@ -70,9 +91,7 @@ }, "/api/conversations/{conversation_id}/events/search": { "get": { - "tags": [ - "Events" - ], + "tags": ["Events"], "summary": "Search Conversation Events", "description": "Search / List local events", "operationId": "search_conversation_events_api_conversations__conversation_id__events_search_get", @@ -131,6 +150,38 @@ "title": "Optional filter by event kind/type (e.g., ActionEvent, MessageEvent)" } }, + { + "name": "source", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Optional filter by event source (e.g., agent, user, environment)" + } + }, + { + "name": "body", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Optional filter by message content (case-insensitive)" + } + }, { "name": "sort_order", "in": "query", @@ -140,6 +191,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": { @@ -171,9 +256,7 @@ }, "/api/conversations/{conversation_id}/events/count": { "get": { - "tags": [ - "Events" - ], + "tags": ["Events"], "summary": "Count Conversation Events", "description": "Count local events matching the given filters", "operationId": "count_conversation_events_api_conversations__conversation_id__events_count_get", @@ -203,6 +286,72 @@ ], "title": "Optional filter by event kind/type (e.g., ActionEvent, MessageEvent)" } + }, + { + "name": "source", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Optional filter by event source (e.g., agent, user, environment)" + } + }, + { + "name": "body", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Optional filter by message content (case-insensitive)" + } + }, + { + "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": { @@ -235,9 +384,7 @@ }, "/api/conversations/{conversation_id}/events/{event_id}": { "get": { - "tags": [ - "Events" - ], + "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", @@ -268,58 +415,7 @@ "content": { "application/json": { "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/Condensation" - }, - { - "$ref": "#/components/schemas/CondensationRequest" - }, - { - "$ref": "#/components/schemas/CondensationSummaryEvent" - }, - { - "$ref": "#/components/schemas/ConversationStateUpdateEvent" - }, - { - "$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/PauseEvent" - } - ], - "title": "Response Get Conversation Event Api Conversations Conversation Id Events Event Id Get", - "discriminator": { - "propertyName": "kind", - "mapping": { - "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_state__ConversationStateUpdateEvent-Output__1": "#/components/schemas/ConversationStateUpdateEvent", - "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__user_action__PauseEvent-Output__1": "#/components/schemas/PauseEvent" - } - } + "$ref": "#/components/schemas/Event" } } } @@ -342,9 +438,7 @@ }, "/api/conversations/{conversation_id}/events": { "get": { - "tags": [ - "Events" - ], + "tags": ["Events"], "summary": "Batch Get Conversation Events", "description": "Get a batch of local events given their ids, returning null for any\nmissing item.", "operationId": "batch_get_conversation_events_api_conversations__conversation_id__events_get", @@ -409,9 +503,7 @@ } }, "post": { - "tags": [ - "Events" - ], + "tags": ["Events"], "summary": "Send Message", "description": "Send a message to a conversation", "operationId": "send_message_api_conversations__conversation_id__events_post", @@ -463,9 +555,7 @@ }, "/api/conversations/{conversation_id}/events/respond_to_confirmation": { "post": { - "tags": [ - "Events" - ], + "tags": ["Events"], "summary": "Respond To Confirmation", "description": "Accept or reject a pending action in confirmation mode.", "operationId": "respond_to_confirmation_api_conversations__conversation_id__events_respond_to_confirmation_post", @@ -520,9 +610,7 @@ }, "/api/conversations/search": { "get": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Search Conversations", "description": "Search / List conversations", "operationId": "search_conversations_api_conversations_search_get", @@ -562,13 +650,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" } }, { @@ -608,9 +696,7 @@ }, "/api/conversations/count": { "get": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Count Conversations", "description": "Count conversations matching the given filters", "operationId": "count_conversations_api_conversations_count_get", @@ -622,13 +708,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" } } ], @@ -659,9 +745,7 @@ }, "/api/conversations/{conversation_id}": { "get": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Get Conversation", "description": "Given an id, get a conversation", "operationId": "get_conversation_api_conversations__conversation_id__get", @@ -704,9 +788,7 @@ } }, "delete": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Delete Conversation", "description": "Permanently delete a conversation.", "operationId": "delete_conversation_api_conversations__conversation_id__delete", @@ -749,9 +831,7 @@ } }, "patch": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Update Conversation", "description": "Update conversation metadata.\n\nThis endpoint allows updating conversation details like title.", "operationId": "update_conversation_api_conversations__conversation_id__patch", @@ -804,11 +884,54 @@ } } }, - "/api/conversations": { + "/api/conversations/{conversation_id}/agent_final_response": { "get": { - "tags": [ - "Conversations" + "tags": ["Conversations"], + "summary": "Get Conversation Agent Final Response", + "description": "Get the agent's final response for a conversation.\n\nReturns the text of the last agent finish message (FinishAction) or\nthe last agent text response (MessageEvent). Returns an empty string\nif the agent has not produced a final response yet.", + "operationId": "get_conversation_agent_final_response_api_conversations__conversation_id__agent_final_response_get", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" + } + } ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AgentResponseResult" + } + } + } + }, + "404": { + "description": "Conversation not found" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/conversations": { + "get": { + "tags": ["Conversations"], "summary": "Batch Get Conversations", "description": "Get a batch of conversations given their ids, returning null for\nany missing item", "operationId": "batch_get_conversations_api_conversations_get", @@ -862,9 +985,7 @@ } }, "post": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Start Conversation", "description": "Start a conversation in the local environment.", "operationId": "start_conversation_api_conversations_post", @@ -876,34 +997,41 @@ "$ref": "#/components/schemas/StartConversationRequest", "examples": [ { + "workspace": { + "working_dir": "workspace/project", + "kind": "LocalWorkspace" + }, + "initial_message": { + "content": [ + { + "text": "Flip a coin!" + } + ] + }, "agent": { "llm": { "model": "your-model-provider/your-model-name", "api_key": "**********", - "reasoning_effort": "high", "usage_id": "your-llm-service" }, "tools": [ { - "name": "BashTool" + "name": "terminal" }, { - "name": "FileEditorTool" + "name": "file_editor" }, { - "name": "TaskTrackerTool" - } - ] - }, - "workspace": { - "working_dir": "workspace/project" - }, - "initial_message": { - "content": [ + "name": "task_tracker" + }, { - "text": "Flip a coin!" + "name": "browser_tool_set" } - ] + ], + "system_prompt_kwargs": { + "llm_security_analyzer": true + }, + "kind": "Agent" } } ] @@ -937,9 +1065,7 @@ }, "/api/conversations/{conversation_id}/pause": { "post": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Pause Conversation", "description": "Pause a conversation, allowing it to be resumed later.", "operationId": "pause_conversation_api_conversations__conversation_id__pause_post", @@ -984,9 +1110,7 @@ }, "/api/conversations/{conversation_id}/run": { "post": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Run Conversation", "description": "Start running the conversation in the background.", "operationId": "run_conversation_api_conversations__conversation_id__run_post", @@ -1034,9 +1158,7 @@ }, "/api/conversations/{conversation_id}/secrets": { "post": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Update Conversation Secrets", "description": "Update secrets for a conversation.", "operationId": "update_conversation_secrets_api_conversations__conversation_id__secrets_post", @@ -1091,9 +1213,7 @@ }, "/api/conversations/{conversation_id}/confirmation_policy": { "post": { - "tags": [ - "Conversations" - ], + "tags": ["Conversations"], "summary": "Set Conversation Confirmation Policy", "description": "Set the confirmation policy for a conversation.", "operationId": "set_conversation_confirmation_policy_api_conversations__conversation_id__confirmation_policy_post", @@ -1146,14 +1266,12 @@ } } }, - "/api/conversations/{conversation_id}/generate_title": { + "/api/conversations/{conversation_id}/security_analyzer": { "post": { - "tags": [ - "Conversations" - ], - "summary": "Generate Conversation Title", - "description": "Generate a title for the conversation using LLM.", - "operationId": "generate_conversation_title_api_conversations__conversation_id__generate_title_post", + "tags": ["Conversations"], + "summary": "Set Conversation Security Analyzer", + "description": "Set the security analyzer for a conversation.", + "operationId": "set_conversation_security_analyzer_api_conversations__conversation_id__security_analyzer_post", "parameters": [ { "name": "conversation_id", @@ -1171,7 +1289,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GenerateTitleRequest" + "$ref": "#/components/schemas/SetSecurityAnalyzerRequest" } } } @@ -1182,7 +1300,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/GenerateTitleResponse" + "$ref": "#/components/schemas/Success" } } } @@ -1203,161 +1321,51 @@ } } }, - "/api/tools/": { - "get": { - "tags": [ - "Tools" - ], - "summary": "List Available Tools", - "description": "List all available tools.", - "operationId": "list_available_tools_api_tools__get", - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Response List Available Tools Api Tools Get" - } - } - } - } - } - } - }, - "/api/bash/bash_events/search": { - "get": { - "tags": [ - "Bash" - ], - "summary": "Search Bash Events", - "description": "Search / List bash event events", - "operationId": "search_bash_events_api_bash_bash_events_search_get", + "/api/conversations/{conversation_id}/switch_profile": { + "post": { + "tags": ["Conversations"], + "summary": "Switch Conversation Profile", + "description": "Switch the conversation's LLM profile to a named profile.", + "operationId": "switch_conversation_profile_api_conversations__conversation_id__switch_profile_post", "parameters": [ { - "name": "kind__eq", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "enum": [ - "BashCommand", - "BashOutput" - ], - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Kind Eq" - } - }, - { - "name": "command_id__eq", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string", - "format": "uuid" - }, - { - "type": "null" - } - ], - "title": "Command Id Eq" - } - }, - { - "name": "timestamp__gte", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string", - "format": "date-time" - }, - { - "type": "null" - } - ], - "title": "Timestamp Gte" - } - }, - { - "name": "timestamp__lt", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string", - "format": "date-time" - }, - { - "type": "null" - } - ], - "title": "Timestamp Lt" - } - }, - { - "name": "sort_order", - "in": "query", - "required": false, - "schema": { - "$ref": "#/components/schemas/BashEventSortOrder", - "default": "TIMESTAMP" - } - }, - { - "name": "page_id", - "in": "query", - "required": false, - "schema": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Optional next_page_id from the previously returned page" - } - }, - { - "name": "limit", - "in": "query", - "required": false, + "name": "conversation_id", + "in": "path", + "required": true, "schema": { - "type": "integer", - "exclusiveMinimum": 0, - "title": "The max number of results in the page", - "lte": 100, - "default": 100 + "type": "string", + "format": "uuid", + "title": "Conversation Id" } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BashEventPage" + "$ref": "#/components/schemas/Success" } } } }, + "400": { + "description": "Invalid or corrupted profile" + }, + "404": { + "description": "Conversation or profile not found" + }, "422": { "description": "Validation Error", "content": { @@ -1371,53 +1379,47 @@ } } }, - "/api/bash/bash_events/{event_id}": { - "get": { - "tags": [ - "Bash" - ], - "summary": "Get Bash Event", - "description": "Get a bash event event given an id", - "operationId": "get_bash_event_api_bash_bash_events__event_id__get", + "/api/conversations/{conversation_id}/switch_llm": { + "post": { + "tags": ["Conversations"], + "summary": "Switch Conversation Llm", + "description": "Swap the conversation's LLM to a caller-supplied object.\n\nUsed by app-servers that own the LLM directly and don't push profiles\nto the agent-server's filesystem (see #3017).", + "operationId": "switch_conversation_llm_api_conversations__conversation_id__switch_llm_post", "parameters": [ { - "name": "event_id", + "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", - "title": "Event Id" + "format": "uuid", + "title": "Conversation Id" } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post" + } + } + } + }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "oneOf": [ - { - "$ref": "#/components/schemas/BashCommand" - }, - { - "$ref": "#/components/schemas/BashOutput" - } - ], - "title": "Response Get Bash Event Api Bash Bash Events Event Id Get", - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__agent_server__models__BashCommand-Output__1": "#/components/schemas/BashCommand", - "openhands__agent_server__models__BashOutput-Output__1": "#/components/schemas/BashOutput" - } - } + "$ref": "#/components/schemas/Success" } } } }, "404": { - "description": "Item not found" + "description": "Conversation not found" }, "422": { "description": "Validation Error", @@ -1432,27 +1434,33 @@ } } }, - "/api/bash/bash_events/": { - "get": { - "tags": [ - "Bash" + "/api/conversations/{conversation_id}/ask_agent": { + "post": { + "tags": ["Conversations"], + "summary": "Ask Agent", + "description": "Ask the agent a simple question without affecting conversation state.", + "operationId": "ask_agent_api_conversations__conversation_id__ask_agent_post", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" + } + } ], - "summary": "Batch Get Bash Events", - "description": "Get a batch of bash event events given their ids, returning null for any\nmissing item.", - "operationId": "batch_get_bash_events_api_bash_bash_events__get", "requestBody": { + "required": true, "content": { "application/json": { "schema": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Event Ids" + "$ref": "#/components/schemas/AskAgentRequest" } } - }, - "required": true + } }, "responses": { "200": { @@ -1460,22 +1468,14 @@ "content": { "application/json": { "schema": { - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/BashEventBase" - }, - { - "type": "null" - } - ] - }, - "type": "array", - "title": "Response Batch Get Bash Events Api Bash Bash Events Get" + "$ref": "#/components/schemas/AskAgentResponse" } } } }, + "404": { + "description": "Item not found" + }, "422": { "description": "Validation Error", "content": { @@ -1489,35 +1489,38 @@ } } }, - "/api/bash/start_bash_command": { + "/api/conversations/{conversation_id}/condense": { "post": { - "tags": [ - "Bash" - ], - "summary": "Start Bash Command", - "description": "Execute a bash command in the background", - "operationId": "start_bash_command_api_bash_start_bash_command_post", - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ExecuteBashRequest" - } + "tags": ["Conversations"], + "summary": "Condense Conversation", + "description": "Force condensation of the conversation history.", + "operationId": "condense_conversation_api_conversations__conversation_id__condense_post", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" } - }, - "required": true - }, + } + ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BashCommand" + "$ref": "#/components/schemas/Success" } } } }, + "404": { + "description": "Item not found" + }, "422": { "description": "Validation Error", "content": { @@ -1531,35 +1534,53 @@ } } }, - "/api/bash/execute_bash_command": { + "/api/conversations/{conversation_id}/fork": { "post": { - "tags": [ - "Bash" + "tags": ["Conversations"], + "summary": "Fork Conversation", + "description": "Fork a conversation, deep-copying its event history.\n\nThe fork starts in ``idle`` status with a fresh event loop.\nCalling ``run`` on the fork resumes from the copied state, meaning\nthe agent has full event memory of the source conversation.", + "operationId": "fork_conversation_api_conversations__conversation_id__fork_post", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" + } + } ], - "summary": "Execute Bash Command", - "description": "Execute a bash command and wait for a result", - "operationId": "execute_bash_command_api_bash_execute_bash_command_post", "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ExecuteBashRequest" + "$ref": "#/components/schemas/ForkConversationRequest", + "default": { + "reset_metrics": true + } } } - }, - "required": true + } }, "responses": { - "200": { - "description": "Successful Response", + "201": { + "description": "Forked conversation created", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/BashOutput" + "$ref": "#/components/schemas/ConversationInfo" } } } }, + "404": { + "description": "Source conversation not found" + }, + "409": { + "description": "Fork ID already in use" + }, "422": { "description": "Validation Error", "content": { @@ -1573,70 +1594,76 @@ } } }, - "/api/bash/bash_events": { - "delete": { - "tags": [ - "Bash" - ], - "summary": "Clear All Bash Events", - "description": "Clear all bash events from storage", - "operationId": "clear_all_bash_events_api_bash_bash_events_delete", - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "additionalProperties": { - "type": "integer" - }, - "type": "object", - "title": "Response Clear All Bash Events Api Bash Bash Events Delete" + "/api/acp/conversations/search": { + "get": { + "tags": ["ACP Conversations"], + "summary": "Search Acp Conversations", + "description": "Search conversations using the ACP-capable contract.\n\nDeprecated since v1.22.0 and scheduled for removal in v1.27.0.\nUse ``/api/conversations/search`` instead.", + "operationId": "search_acp_conversations_api_acp_conversations_search_get", + "deprecated": true, + "parameters": [ + { + "name": "page_id", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" } - } + ], + "title": "Optional next_page_id from the previously returned page" } - } - } - } - }, - "/api/file/upload/{path}": { - "post": { - "tags": [ - "Files" - ], - "summary": "Upload File", - "description": "Upload a file to the workspace.", - "operationId": "upload_file_api_file_upload__path__post", - "parameters": [ + }, { - "name": "path", - "in": "path", - "required": true, + "name": "limit", + "in": "query", + "required": false, "schema": { - "type": "string", - "description": "Absolute file path.", - "title": "Path" - }, - "description": "Absolute file path." - } - ], - "requestBody": { - "required": true, - "content": { - "multipart/form-data": { - "schema": { - "$ref": "#/components/schemas/Body_upload_file_api_file_upload__path__post" - } + "type": "integer", + "exclusiveMinimum": 0, + "title": "The max number of results in the page", + "lte": 100, + "default": 100 + } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/ConversationExecutionStatus" + }, + { + "type": "null" + } + ], + "title": "Optional filter by conversation execution status" + } + }, + { + "name": "sort_order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/ConversationSortOrder", + "title": "Sort order for conversations", + "default": "CREATED_AT_DESC" } } - }, + ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Success" + "$ref": "#/components/schemas/ConversationPage" } } } @@ -1654,25 +1681,29 @@ } } }, - "/api/file/download/{path}": { + "/api/acp/conversations/count": { "get": { - "tags": [ - "Files" - ], - "summary": "Download File", - "description": "Download a file from the workspace.", - "operationId": "download_file_api_file_download__path__get", + "tags": ["ACP Conversations"], + "summary": "Count Acp Conversations", + "description": "Count conversations using the ACP-capable contract.\n\nDeprecated since v1.22.0 and scheduled for removal in v1.27.0.\nUse ``/api/conversations/count`` instead.", + "operationId": "count_acp_conversations_api_acp_conversations_count_get", + "deprecated": true, "parameters": [ { - "name": "path", - "in": "path", - "required": true, + "name": "status", + "in": "query", + "required": false, "schema": { - "type": "string", - "description": "Absolute file path.", - "title": "Path" - }, - "description": "Absolute file path." + "anyOf": [ + { + "$ref": "#/components/schemas/ConversationExecutionStatus" + }, + { + "type": "null" + } + ], + "title": "Optional filter by conversation execution status" + } } ], "responses": { @@ -1680,7 +1711,10 @@ "description": "Successful Response", "content": { "application/json": { - "schema": {} + "schema": { + "type": "integer", + "title": "Response Count Acp Conversations Api Acp Conversations Count Get" + } } } }, @@ -1697,33 +1731,22 @@ } } }, - "/api/vscode/url": { + "/api/acp/conversations/{conversation_id}": { "get": { - "tags": [ - "VSCode" - ], - "summary": "Get Vscode Url", - "description": "Get the VSCode URL with authentication token.\n\nArgs:\n base_url: Base URL for the VSCode server (default: http://localhost:8001)\n workspace_dir: Path to workspace directory\n\nReturns:\n VSCode URL with token if available, None otherwise", - "operationId": "get_vscode_url_api_vscode_url_get", + "tags": ["ACP Conversations"], + "summary": "Get Acp Conversation", + "description": "Get a conversation using the ACP-capable contract.\n\nDeprecated since v1.22.0 and scheduled for removal in v1.27.0.\nUse ``/api/conversations/{conversation_id}`` instead.", + "operationId": "get_acp_conversation_api_acp_conversations__conversation_id__get", + "deprecated": true, "parameters": [ { - "name": "base_url", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "http://localhost:8001", - "title": "Base Url" - } - }, - { - "name": "workspace_dir", - "in": "query", - "required": false, + "name": "conversation_id", + "in": "path", + "required": true, "schema": { "type": "string", - "default": "workspace", - "title": "Workspace Dir" + "format": "uuid", + "title": "Conversation Id" } } ], @@ -1733,11 +1756,14 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/VSCodeUrlResponse" + "$ref": "#/components/schemas/ConversationInfo" } } } }, + "404": { + "description": "Item not found" + }, "422": { "description": "Validation Error", "content": { @@ -1751,66 +1777,46 @@ } } }, - "/api/vscode/status": { + "/api/acp/conversations": { "get": { - "tags": [ - "VSCode" + "tags": ["ACP Conversations"], + "summary": "Batch Get Acp Conversations", + "description": "Batch get conversations using the ACP-capable contract.\n\nDeprecated since v1.22.0 and scheduled for removal in v1.27.0.\nUse ``/api/conversations`` instead.", + "operationId": "batch_get_acp_conversations_api_acp_conversations_get", + "deprecated": true, + "parameters": [ + { + "name": "ids", + "in": "query", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "title": "Ids" + } + } ], - "summary": "Get Vscode Status", - "description": "Get the VSCode server status.\n\nReturns:\n Dictionary with running status and enabled status", - "operationId": "get_vscode_status_api_vscode_status_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { - "additionalProperties": { + "type": "array", + "items": { "anyOf": [ { - "type": "boolean" + "$ref": "#/components/schemas/ConversationInfo" }, { - "type": "string" + "type": "null" } ] }, - "type": "object", - "title": "Response Get Vscode Status Api Vscode Status Get" - } - } - } - } - } - } - }, - "/api/desktop/url": { - "get": { - "tags": [ - "Desktop" - ], - "summary": "Get Desktop Url", - "description": "Get the noVNC URL for desktop access.\n\nArgs:\n base_url: Base URL for the noVNC server (default: http://localhost:8002)\n\nReturns:\n noVNC URL if available, None otherwise", - "operationId": "get_desktop_url_api_desktop_url_get", - "parameters": [ - { - "name": "base_url", - "in": "query", - "required": false, - "schema": { - "type": "string", - "default": "http://localhost:8002", - "title": "Base Url" - } - } - ], - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DesktopUrlResponse" + "title": "Response Batch Get Acp Conversations Api Acp Conversations Get" } } } @@ -1826,211 +1832,11951 @@ } } } - } - }, - "/": { - "get": { - "summary": "Get Server Info", - "operationId": "get_server_info__get", - "responses": { - "200": { - "description": "Successful Response", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ServerInfo" - } - } - } - } - } - } - } - }, - "components": { - "schemas": { - "ActionEvent": { - "properties": { - "kind": { - "type": "string", - "const": "ActionEvent", - "title": "Kind", - "default": "ActionEvent" - }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" - }, + }, + "post": { + "tags": ["ACP Conversations"], + "summary": "Start Acp Conversation", + "description": "Start a conversation using the ACP-capable contract.\n\nDeprecated since v1.22.0 and scheduled for removal in v1.27.0.\nUse ``/api/conversations`` instead; it now accepts ACP agents and\n``agent_settings`` payloads.", + "operationId": "start_acp_conversation_api_acp_conversations_post", + "deprecated": true, + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StartACPConversationRequest", + "examples": [ + { + "workspace": { + "working_dir": "workspace/project", + "kind": "LocalWorkspace" + }, + "initial_message": { + "content": [ + { + "text": "Flip a coin!" + } + ] + }, + "agent": { + "llm": { + "model": "your-model-provider/your-model-name", + "api_key": "**********", + "usage_id": "your-llm-service" + }, + "tools": [ + { + "name": "terminal" + }, + { + "name": "file_editor" + }, + { + "name": "task_tracker" + }, + { + "name": "browser_tool_set" + } + ], + "system_prompt_kwargs": { + "llm_security_analyzer": true + }, + "kind": "Agent" + } + }, + { + "workspace": { + "working_dir": "workspace/project", + "kind": "LocalWorkspace" + }, + "initial_message": { + "content": [ + { + "text": "Inspect the repository and summarize it." + } + ] + }, + "agent": { + "acp_command": ["npx", "-y", "claude-agent-acp"], + "acp_env": {}, + "kind": "ACPAgent" + } + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConversationInfo" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/tools/": { + "get": { + "tags": ["Tools"], + "summary": "List Available Tools", + "description": "List all available tools.", + "operationId": "list_available_tools_api_tools__get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Response List Available Tools Api Tools Get" + } + } + } + } + } + } + }, + "/api/bash/bash_events/search": { + "get": { + "tags": ["Bash"], + "summary": "Search Bash Events", + "description": "Search / List bash event events", + "operationId": "search_bash_events_api_bash_bash_events_search_get", + "parameters": [ + { + "name": "kind__eq", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "enum": ["BashCommand", "BashOutput"], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Kind Eq" + } + }, + { + "name": "command_id__eq", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "uuid" + }, + { + "type": "null" + } + ], + "title": "Command Id Eq" + } + }, + { + "name": "timestamp__gte", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Timestamp Gte" + } + }, + { + "name": "timestamp__lt", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Timestamp Lt" + } + }, + { + "name": "order__gt", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Filter to events with order greater than this value", + "description": "Only returns BashOutput events with order > this value. Useful for polling to fetch only new events since the last poll." + }, + "description": "Only returns BashOutput events with order > this value. Useful for polling to fetch only new events since the last poll." + }, + { + "name": "sort_order", + "in": "query", + "required": false, + "schema": { + "$ref": "#/components/schemas/BashEventSortOrder", + "default": "TIMESTAMP" + } + }, + { + "name": "page_id", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Optional next_page_id from the previously returned page" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "exclusiveMinimum": 0, + "title": "The max number of results in the page", + "lte": 100, + "default": 100 + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BashEventPage" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/bash/bash_events/{event_id}": { + "get": { + "tags": ["Bash"], + "summary": "Get Bash Event", + "description": "Get a bash event event given an id", + "operationId": "get_bash_event_api_bash_bash_events__event_id__get", + "parameters": [ + { + "name": "event_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Event Id" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BashEventBase" + } + } + } + }, + "404": { + "description": "Item not found" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/bash/bash_events/": { + "get": { + "tags": ["Bash"], + "summary": "Batch Get Bash Events", + "description": "Get a batch of bash event events given their ids, returning null for any\nmissing item.", + "operationId": "batch_get_bash_events_api_bash_bash_events__get", + "requestBody": { + "content": { + "application/json": { + "schema": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Event Ids" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/BashEventBase" + }, + { + "type": "null" + } + ] + }, + "type": "array", + "title": "Response Batch Get Bash Events Api Bash Bash Events Get" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/bash/start_bash_command": { + "post": { + "tags": ["Bash"], + "summary": "Start Bash Command", + "description": "Execute a bash command in the background", + "operationId": "start_bash_command_api_bash_start_bash_command_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteBashRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BashCommand" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/bash/execute_bash_command": { + "post": { + "tags": ["Bash"], + "summary": "Execute Bash Command", + "description": "Execute a bash command and wait for a result", + "operationId": "execute_bash_command_api_bash_execute_bash_command_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ExecuteBashRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BashOutput" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/bash/bash_events": { + "delete": { + "tags": ["Bash"], + "summary": "Clear All Bash Events", + "description": "Clear all bash events from storage", + "operationId": "clear_all_bash_events_api_bash_bash_events_delete", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "additionalProperties": { + "type": "integer" + }, + "type": "object", + "title": "Response Clear All Bash Events Api Bash Bash Events Delete" + } + } + } + } + } + } + }, + "/api/git/changes": { + "get": { + "tags": ["Git"], + "summary": "Git Changes Query", + "description": "Get git changes using query parameter (preferred method).", + "operationId": "git_changes_query_api_git_changes_get", + "parameters": [ + { + "name": "path", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "The git repository path", + "title": "Path" + }, + "description": "The git repository path" + }, + { + "name": "ref", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Optional git ref to diff against (e.g. 'HEAD' for git status-style changes, or a commit hash). When omitted, the upstream/default branch is auto-detected.", + "title": "Ref" + }, + "description": "Optional git ref to diff against (e.g. 'HEAD' for git status-style changes, or a commit hash). When omitted, the upstream/default branch is auto-detected." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/GitChange" + }, + "title": "Response Git Changes Query Api Git Changes Get" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/git/diff": { + "get": { + "tags": ["Git"], + "summary": "Git Diff Query", + "description": "Get git diff using query parameter (preferred method).", + "operationId": "git_diff_query_api_git_diff_get", + "parameters": [ + { + "name": "path", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "The file path to get diff for", + "title": "Path" + }, + "description": "The file path to get diff for" + }, + { + "name": "ref", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Optional git ref to diff against (e.g. 'HEAD' for git status-style changes, or a commit hash). When omitted, the upstream/default branch is auto-detected.", + "title": "Ref" + }, + "description": "Optional git ref to diff against (e.g. 'HEAD' for git status-style changes, or a commit hash). When omitted, the upstream/default branch is auto-detected." + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GitDiff" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/file/upload": { + "post": { + "tags": ["Files"], + "summary": "Upload File Query", + "description": "Upload a file to the workspace using query parameter (preferred method).", + "operationId": "upload_file_query_api_file_upload_post", + "parameters": [ + { + "name": "path", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "Absolute file path", + "title": "Path" + }, + "description": "Absolute file path" + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/Body_upload_file_query_api_file_upload_post" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Success" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/file/download": { + "get": { + "tags": ["Files"], + "summary": "Download File Query", + "description": "Download a file from the workspace using query parameter (preferred method).", + "operationId": "download_file_query_api_file_download_get", + "parameters": [ + { + "name": "path", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "Absolute file path", + "title": "Path" + }, + "description": "Absolute file path" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/file/home": { + "get": { + "tags": ["Files"], + "summary": "Get Home Directory", + "description": "Return the agent-server user's home directory and dynamic sidebar lists.\n\n``favorites`` is the set of visible top-level directories actually present\nin the user's home (so it reflects the real environment instead of a\nhardcoded list of names that may not exist). ``locations`` is the set of\nfilesystem roots — '/' on POSIX or available drive letters on Windows.", + "operationId": "get_home_directory_api_file_home_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HomeResponse" + } + } + } + } + } + } + }, + "/api/file/search_subdirs": { + "get": { + "tags": ["Files"], + "summary": "Search Subdirs", + "description": "Search / List immediate subdirectories of `path`.\n\nUsed by the GUI's workspace picker. Hidden entries (names starting with '.')\nand symlinks are skipped. Files are skipped. Returns absolute paths so the\nGUI can use a result directly as ``workspace.working_dir``.\n\nResults are sorted case-insensitively by name and paginated. ``page_id`` is\nthe ``next_page_id`` returned by the previous page (the lowercase name of\nthe first item to include on the next page).", + "operationId": "search_subdirs_api_file_search_subdirs_get", + "parameters": [ + { + "name": "path", + "in": "query", + "required": true, + "schema": { + "type": "string", + "description": "Absolute directory path to list subdirectories of", + "title": "Path" + }, + "description": "Absolute directory path to list subdirectories of" + }, + { + "name": "page_id", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Optional next_page_id from the previously returned page" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "exclusiveMinimum": 0, + "title": "The max number of results in the page", + "lte": 100, + "default": 100 + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SubdirectoryPage" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/file/download-trajectory/{conversation_id}": { + "get": { + "tags": ["Files"], + "summary": "Download Trajectory", + "description": "Download a zip archive of a conversation trajectory.", + "operationId": "download_trajectory_api_file_download_trajectory__conversation_id__get", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/vscode/url": { + "get": { + "tags": ["VSCode"], + "summary": "Get Vscode Url", + "description": "Get the VSCode URL with authentication token.\n\nArgs:\n base_url: Base URL for the VSCode server (default: http://localhost:8001)\n workspace_dir: Path to workspace directory\n\nReturns:\n VSCode URL with token if available, None otherwise", + "operationId": "get_vscode_url_api_vscode_url_get", + "parameters": [ + { + "name": "base_url", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "http://localhost:8001", + "title": "Base Url" + } + }, + { + "name": "workspace_dir", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "workspace", + "title": "Workspace Dir" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VSCodeUrlResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/vscode/status": { + "get": { + "tags": ["VSCode"], + "summary": "Get Vscode Status", + "description": "Get the VSCode server status.\n\nReturns:\n Dictionary with running status and enabled status", + "operationId": "get_vscode_status_api_vscode_status_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "additionalProperties": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string" + } + ] + }, + "type": "object", + "title": "Response Get Vscode Status Api Vscode Status Get" + } + } + } + } + } + } + }, + "/api/desktop/url": { + "get": { + "tags": ["Desktop"], + "summary": "Get Desktop Url", + "description": "Get the noVNC URL for desktop access.\n\nArgs:\n base_url: Base URL for the noVNC server (default: http://localhost:8002)\n\nReturns:\n noVNC URL if available, None otherwise", + "operationId": "get_desktop_url_api_desktop_url_get", + "parameters": [ + { + "name": "base_url", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "http://localhost:8002", + "title": "Base Url" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DesktopUrlResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/skills": { + "post": { + "tags": ["Skills"], + "summary": "Get Skills", + "description": "Load and merge skills from all configured sources.\n\nSkills are loaded from multiple sources and merged with the following\nprecedence (later overrides earlier for duplicate names):\n1. Sandbox skills (lowest) - Exposed URLs from sandbox\n2. Public skills - From GitHub OpenHands/extensions repository\n3. User skills - From ~/.openhands/skills/\n4. Organization skills - From {org}/.openhands or equivalent\n5. Project skills (highest) - From {workspace}/.openhands/skills/\n\nArgs:\n request: SkillsRequest containing configuration for which sources to load.\n\nReturns:\n SkillsResponse containing merged skills and source counts.", + "operationId": "get_skills_api_skills_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillsRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SkillsResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/skills/sync": { + "post": { + "tags": ["Skills"], + "summary": "Sync Skills", + "description": "Force refresh of public skills from GitHub repository.\n\nThis triggers a git pull on the cached skills repository to get\nthe latest skills from the OpenHands/extensions repository.\n\nReturns:\n SyncResponse indicating success or failure.", + "operationId": "sync_skills_api_skills_sync_post", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SyncResponse" + } + } + } + } + } + } + }, + "/api/hooks": { + "post": { + "tags": ["Hooks"], + "summary": "Get Hooks", + "description": "Load hooks from the workspace .openhands/hooks.json file.\n\nThis endpoint reads the hooks configuration from the project's\n.openhands/hooks.json file if it exists.\n\nArgs:\n request: HooksRequest containing the project directory path.\n\nReturns:\n HooksResponse containing the hook configuration or None.", + "operationId": "get_hooks_api_hooks_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HooksRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HooksResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/llm/providers": { + "get": { + "tags": ["LLM"], + "summary": "List Providers", + "description": "List all available LLM providers supported by LiteLLM.", + "operationId": "list_providers_api_llm_providers_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProvidersResponse" + } + } + } + } + } + } + }, + "/api/llm/models": { + "get": { + "tags": ["LLM"], + "summary": "List Models", + "description": "List all available LLM models supported by LiteLLM.\n\nArgs:\n provider: Optional provider name to filter models by.\n\nNote: Bedrock models are excluded unless AWS credentials are configured.", + "operationId": "list_models_api_llm_models_get", + "parameters": [ + { + "name": "provider", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Filter models by provider (e.g., 'openai', 'anthropic')", + "title": "Provider" + }, + "description": "Filter models by provider (e.g., 'openai', 'anthropic')" + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModelsResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/llm/models/verified": { + "get": { + "tags": ["LLM"], + "summary": "List Verified Models", + "description": "List all verified LLM models organized by provider.\n\nVerified models are those that have been tested and confirmed to work well\nwith OpenHands.", + "operationId": "list_verified_models_api_llm_models_verified_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VerifiedModelsResponse" + } + } + } + } + } + } + }, + "/api/settings/agent-schema": { + "get": { + "tags": ["Settings"], + "summary": "Get Agent Settings Schema", + "description": "Return the schema used to render AgentSettings-based settings forms.", + "operationId": "get_agent_settings_schema_api_settings_agent_schema_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsSchema" + } + } + } + } + } + } + }, + "/api/settings/conversation-schema": { + "get": { + "tags": ["Settings"], + "summary": "Get Conversation Settings Schema", + "description": "Return the schema used to render ConversationSettings-based forms.", + "operationId": "get_conversation_settings_schema_api_settings_conversation_schema_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsSchema" + } + } + } + } + } + } + }, + "/api/settings": { + "get": { + "tags": ["Settings"], + "summary": "Get Settings", + "description": "Get current settings.\n\nReturns the persisted settings including agent configuration,\nconversation settings, and whether an LLM API key is configured.\n\nUse the ``X-Expose-Secrets`` header to control secret exposure:\n- ``encrypted``: Returns cipher-encrypted values (safe for frontend clients)\n- ``plaintext``: Returns raw secret values (backend clients only!)\n- (absent): Returns redacted values (\"**********\")\n\nSecurity:\n When the server is configured with ``session_api_keys``, all endpoints\n under ``/api`` (including this one) require the ``X-Session-API-Key``\n header. When no session API keys are configured, endpoints are open.\n\n **Trust model:** All authenticated clients are treated as equally\n trusted. There is no role-based authorization for ``X-Expose-Secrets``\n modes—any authenticated client can request ``plaintext`` or\n ``encrypted`` exposure. This design assumes:\n\n - All clients sharing session API keys operate in the same trust domain\n - Network-level controls (firewalls, VPCs) restrict access to trusted\n clients only\n - Production deployments use session API keys to prevent anonymous access\n\n The ``plaintext`` mode exists for backend-to-backend communication\n (e.g., RemoteWorkspace). Frontend clients should prefer ``encrypted``\n mode for round-tripping secrets, or omit the header to receive redacted\n values.", + "operationId": "get_settings_api_settings_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsResponse" + } + } + } + } + } + }, + "patch": { + "tags": ["Settings"], + "summary": "Update Settings", + "description": "Update settings with partial changes.\n\nAccepts ``agent_settings_diff`` and/or ``conversation_settings_diff``\nfor incremental updates. Values are deep-merged with existing settings.\n\nUses file locking to prevent concurrent updates from overwriting each other.\n\nRaises:\n HTTPException: 400 if the update payload contains invalid values.", + "operationId": "update_settings_api_settings_patch", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsUpdateRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SettingsResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/settings/secrets": { + "get": { + "tags": ["Settings"], + "summary": "List Secrets", + "description": "List all available secrets (names and descriptions only, no values).", + "operationId": "list_secrets_api_settings_secrets_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretsListResponse" + } + } + } + } + } + }, + "put": { + "tags": ["Settings"], + "summary": "Create Secret", + "description": "Create or update a custom secret (upsert).\n\nRaises:\n HTTPException: 400 if secret name format is invalid, 500 if file is corrupted.", + "operationId": "create_secret_api_settings_secrets_put", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SecretItemResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/settings/secrets/{name}": { + "get": { + "tags": ["Settings"], + "summary": "Get Secret Value", + "description": "Get a single secret value by name.\n\nReturns the raw secret value as plain text. This endpoint is designed\nto be used with LookupSecret for lazy secret resolution.\n\nRaises:\n HTTPException: 400 if name format is invalid, 404 if secret not found.", + "operationId": "get_secret_value_api_settings_secrets__name__get", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": ["Settings"], + "summary": "Delete Secret", + "description": "Delete a custom secret by name.\n\nRaises:\n HTTPException: 400 if name format is invalid, 404 if secret not found,\n 500 if file is corrupted.", + "operationId": "delete_secret_api_settings_secrets__name__delete", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Name" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "type": "boolean" + }, + "title": "Response Delete Secret Api Settings Secrets Name Delete" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/profiles": { + "get": { + "tags": ["Profiles"], + "summary": "List Profiles", + "description": "List all saved LLM profiles.\n\nReturns the list of profiles along with the currently active profile name,\nif one has been activated. The active_profile tracks which LLM profile\nconfiguration is currently in use.\n\nAuto-creates a profile named after the model if:\n- No profiles exist\n- agent_settings.llm has an API key configured\n\nThe API key check ensures we only auto-create when the user has actually\nconfigured their LLM (not just relying on defaults). This allows users\nwith existing LLM configurations to see their settings as a profile\nwithout manual creation.", + "operationId": "list_profiles_api_profiles_get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProfileListResponse" + } + } + } + } + } + } + }, + "/api/profiles/{name}": { + "get": { + "tags": ["Profiles"], + "summary": "Get Profile", + "description": "Get a profile's configuration.\n\nUse the ``X-Expose-Secrets`` header to control secret exposure:\n- ``encrypted``: Returns cipher-encrypted values (safe for frontend clients)\n- ``plaintext``: Returns raw secret values (backend clients only!)\n- (absent): Returns nulled ``api_key`` with ``api_key_set`` indicator", + "operationId": "get_profile_api_profiles__name__get", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", + "title": "Name" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProfileDetailResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": ["Profiles"], + "summary": "Save Profile", + "description": "Save an LLM configuration as a named profile.\n\nOverwrites an existing profile of the same name. Returns 409 if creating\na new profile would exceed ``MAX_PROFILES``.\n\nWhen ``OH_SECRET_KEY`` is configured, secrets are encrypted at rest.\nClients can submit cipher-encrypted secrets which will be decrypted\nserver-side before re-encrypting with the storage cipher.", + "operationId": "save_profile_api_profiles__name__post", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", + "title": "Name" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SaveProfileRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProfileMutationResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": ["Profiles"], + "summary": "Delete Profile", + "description": "Delete a saved profile (idempotent).", + "operationId": "delete_profile_api_profiles__name__delete", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", + "title": "Name" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProfileMutationResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/profiles/{name}/rename": { + "post": { + "tags": ["Profiles"], + "summary": "Rename Profile", + "description": "Rename a saved profile atomically.\n\nReturns 404 if the source does not exist, or 409 if ``new_name`` already\nexists. A same-name rename is a verified no-op (still 404s if missing).\n\nIf the renamed profile is the currently active profile, the active_profile\nsetting is updated to the new name.", + "operationId": "rename_profile_api_profiles__name__rename_post", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", + "title": "Name" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RenameProfileRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProfileMutationResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/profiles/{name}/activate": { + "post": { + "tags": ["Profiles"], + "summary": "Activate Profile", + "description": "Activate a saved LLM profile.\n\nThis endpoint:\n1. Loads the named profile's LLM configuration\n2. Applies it to the current agent settings (updates ``agent_settings.llm``)\n3. Records the profile name as the active profile for frontend tracking\n\nReturns 404 if the profile does not exist.\n\nUse ``GET /api/profiles`` to see which profile is currently active via\nthe ``active_profile`` field.", + "operationId": "activate_profile_api_profiles__name__activate_post", + "parameters": [ + { + "name": "name", + "in": "path", + "required": true, + "schema": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", + "title": "Name" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ActivateProfileResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/cloud-proxy": { + "post": { + "tags": ["Cloud Proxy"], + "summary": "Cloud Proxy", + "operationId": "cloud_proxy_api_cloud_proxy_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CloudProxyRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/auth/workspace-session": { + "post": { + "tags": ["Auth"], + "summary": "Create Workspace Session", + "description": "Mint a workspace-scoped session cookie.\n\nCaller must already be authenticated by the ``X-Session-API-Key``\nheader (enforced by the parent router's dependency). The cookie value\nis the validated session API key itself; it is HttpOnly so JS in\nworkspace HTML cannot read it back.", + "operationId": "create_workspace_session_api_auth_workspace_session_post", + "responses": { + "204": { + "description": "Cookie set" + }, + "401": { + "description": "Missing or invalid X-Session-API-Key header" + } + } + }, + "delete": { + "tags": ["Auth"], + "summary": "Delete Workspace Session", + "description": "Clear the workspace session cookie.\n\nBrowsers identify cookies by ``(name, domain, path)``; the deletion\ncookie must therefore share the original cookie's attributes. We\noverwrite with an empty value and ``max_age=0`` so the browser drops\nit immediately.", + "operationId": "delete_workspace_session_api_auth_workspace_session_delete", + "responses": { + "204": { + "description": "Cookie cleared" + } + } + } + }, + "/api/conversations/{conversation_id}/workspace": { + "get": { + "tags": ["Workspace"], + "summary": "Serve Workspace Root", + "description": "Serve ``index.html`` from the conversation's workspace root.", + "operationId": "serve_workspace_root_api_conversations__conversation_id__workspace_get", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "File or conversation not found" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/conversations/{conversation_id}/workspace/{file_path}": { + "get": { + "tags": ["Workspace"], + "summary": "Serve Workspace File", + "description": "Serve a file (or directory ``index.html``) from the workspace.", + "operationId": "serve_workspace_file_api_conversations__conversation_id__workspace__file_path__get", + "parameters": [ + { + "name": "conversation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "title": "Conversation Id" + } + }, + { + "name": "file_path", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "File Path" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": {} + } + } + }, + "404": { + "description": "File or conversation not found" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/": { + "get": { + "tags": ["Server Details"], + "summary": "Get Server Info", + "operationId": "get_server_info__get", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServerInfo" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "ACPAgent-Input": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Input" + }, + "tools": { + "items": { + "$ref": "#/components/schemas/Tool-Input" + }, + "type": "array", + "title": "Tools" + }, + "mcp_config": { + "additionalProperties": true, + "type": "object", + "title": "Mcp Config", + "description": "Optional MCP configuration dictionary to create MCP tools.", + "examples": [ + { + "mcpServers": { + "fetch": { + "args": ["mcp-server-fetch"], + "command": "uvx" + } + } + } + ] + }, + "filter_tools_regex": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Filter Tools Regex", + "description": "Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added.", + "examples": ["^(?!repomix)(.*)|^repomix.*pack_codebase.*$"] + }, + "include_default_tools": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Include Default Tools" + }, + "agent_context": { + "anyOf": [ + { + "$ref": "#/components/schemas/AgentContext-Input" + }, + { + "type": "null" + } + ], + "description": "Optional AgentContext to initialize the agent with specific context.", + "examples": [ + { + "skills": [ + { + "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + "name": "AGENTS.md", + "type": "repo" + }, + { + "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + "name": "flarglebargle", + "trigger": ["flarglebargle"], + "type": "knowledge" + } + ], + "system_message_suffix": "Always finish your response with the word 'yay!'", + "user_message_prefix": "The first character of your response should be 'I'" + } + ] + }, + "system_prompt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System Prompt", + "description": "Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`.\n\n**Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour." + }, + "system_prompt_filename": { + "type": "string", + "title": "System Prompt Filename", + "description": "System prompt template filename. Can be either:\n- A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_prompt.j2')", + "default": "system_prompt.j2" + }, + "security_policy_filename": { + "type": "string", + "title": "Security Policy Filename", + "description": "Security policy template filename. Can be either:\n- A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_security_policy.j2')\n- Empty string to disable security policy", + "default": "security_policy.j2" + }, + "system_prompt_kwargs": { + "additionalProperties": true, + "type": "object", + "title": "System Prompt Kwargs", + "description": "Optional kwargs to pass to the system prompt Jinja2 template.", + "examples": [ + { + "cli_mode": true + } + ] + }, + "condenser": { + "anyOf": [ + { + "$ref": "#/components/schemas/CondenserBase-Input" + }, + { + "type": "null" + } + ], + "description": "Optional condenser to use for condensing conversation history.", + "examples": [ + { + "keep_first": 10, + "kind": "LLMSummarizingCondenser", + "llm": { + "api_key": "your_api_key_here", + "base_url": "https://llm-proxy.eval.all-hands.dev", + "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + }, + "max_size": 80 + } + ] + }, + "critic": { + "anyOf": [ + { + "$ref": "#/components/schemas/CriticBase-Input" + }, + { + "type": "null" + } + ], + "description": "EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode.", + "examples": [ + { + "kind": "AgentFinishedCritic" + } + ] + }, + "tool_concurrency_limit": { + "type": "integer", + "minimum": 1.0, + "title": "Tool Concurrency Limit", + "description": "Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race.", + "default": 1 + }, + "acp_command": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Acp Command", + "description": "Command to start the ACP server, e.g. ['npx', '-y', '@agentclientprotocol/claude-agent-acp']" + }, + "acp_args": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Acp Args", + "description": "Additional arguments for the ACP server command" + }, + "acp_env": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Acp Env", + "description": "Additional environment variables for the ACP server process" + }, + "acp_session_mode": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Acp Session Mode", + "description": "Session mode ID to set after creating a session. If None (default), auto-detected from the ACP server type: 'bypassPermissions' for claude-agent-acp, 'full-access' for codex-acp." + }, + "acp_prompt_timeout": { + "type": "number", + "title": "Acp Prompt Timeout", + "description": "Timeout in seconds for a single ACP prompt() call. Prevents indefinite hangs when the ACP server fails to respond.", + "default": 1800.0 + }, + "acp_model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Acp Model", + "description": "Model for the ACP server to use (e.g. 'claude-opus-4-6' or 'gpt-5.4'). For Claude ACP, passed via session _meta. For Codex ACP, applied via the protocol-level set_session_model call. If None, the server picks its default." + }, + "kind": { + "type": "string", + "const": "ACPAgent", + "title": "Kind" + } + }, + "type": "object", + "required": ["acp_command"], + "title": "ACPAgent", + "description": "Agent that delegates to an ACP-compatible subprocess server." + }, + "ACPAgent-Output": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Output" + }, + "tools": { + "items": { + "$ref": "#/components/schemas/openhands__sdk__tool__spec__Tool" + }, + "type": "array", + "title": "Tools" + }, + "mcp_config": { + "additionalProperties": true, + "type": "object", + "title": "Mcp Config", + "description": "Optional MCP configuration dictionary to create MCP tools.", + "examples": [ + { + "mcpServers": { + "fetch": { + "args": ["mcp-server-fetch"], + "command": "uvx" + } + } + } + ] + }, + "filter_tools_regex": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Filter Tools Regex", + "description": "Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added.", + "examples": ["^(?!repomix)(.*)|^repomix.*pack_codebase.*$"] + }, + "include_default_tools": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Include Default Tools" + }, + "agent_context": { + "anyOf": [ + { + "$ref": "#/components/schemas/AgentContext-Output" + }, + { + "type": "null" + } + ], + "description": "Optional AgentContext to initialize the agent with specific context.", + "examples": [ + { + "skills": [ + { + "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + "name": "AGENTS.md", + "type": "repo" + }, + { + "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + "name": "flarglebargle", + "trigger": ["flarglebargle"], + "type": "knowledge" + } + ], + "system_message_suffix": "Always finish your response with the word 'yay!'", + "user_message_prefix": "The first character of your response should be 'I'" + } + ] + }, + "system_prompt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System Prompt", + "description": "Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`.\n\n**Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour." + }, + "system_prompt_filename": { + "type": "string", + "title": "System Prompt Filename", + "description": "System prompt template filename. Can be either:\n- A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_prompt.j2')", + "default": "system_prompt.j2" + }, + "security_policy_filename": { + "type": "string", + "title": "Security Policy Filename", + "description": "Security policy template filename. Can be either:\n- A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_security_policy.j2')\n- Empty string to disable security policy", + "default": "security_policy.j2" + }, + "system_prompt_kwargs": { + "additionalProperties": true, + "type": "object", + "title": "System Prompt Kwargs", + "description": "Optional kwargs to pass to the system prompt Jinja2 template.", + "examples": [ + { + "cli_mode": true + } + ] + }, + "condenser": { + "anyOf": [ + { + "$ref": "#/components/schemas/CondenserBase-Output" + }, + { + "type": "null" + } + ], + "description": "Optional condenser to use for condensing conversation history.", + "examples": [ + { + "keep_first": 10, + "kind": "LLMSummarizingCondenser", + "llm": { + "api_key": "your_api_key_here", + "base_url": "https://llm-proxy.eval.all-hands.dev", + "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + }, + "max_size": 80 + } + ] + }, + "critic": { + "anyOf": [ + { + "$ref": "#/components/schemas/CriticBase-Output" + }, + { + "type": "null" + } + ], + "description": "EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode.", + "examples": [ + { + "kind": "AgentFinishedCritic" + } + ] + }, + "tool_concurrency_limit": { + "type": "integer", + "minimum": 1.0, + "title": "Tool Concurrency Limit", + "description": "Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race.", + "default": 1 + }, + "acp_command": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Acp Command", + "description": "Command to start the ACP server, e.g. ['npx', '-y', '@agentclientprotocol/claude-agent-acp']" + }, + "acp_args": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Acp Args", + "description": "Additional arguments for the ACP server command" + }, + "acp_env": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Acp Env", + "description": "Additional environment variables for the ACP server process" + }, + "acp_session_mode": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Acp Session Mode", + "description": "Session mode ID to set after creating a session. If None (default), auto-detected from the ACP server type: 'bypassPermissions' for claude-agent-acp, 'full-access' for codex-acp." + }, + "acp_prompt_timeout": { + "type": "number", + "title": "Acp Prompt Timeout", + "description": "Timeout in seconds for a single ACP prompt() call. Prevents indefinite hangs when the ACP server fails to respond.", + "default": 1800.0 + }, + "acp_model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Acp Model", + "description": "Model for the ACP server to use (e.g. 'claude-opus-4-6' or 'gpt-5.4'). For Claude ACP, passed via session _meta. For Codex ACP, applied via the protocol-level set_session_model call. If None, the server picks its default." + }, + "kind": { + "type": "string", + "const": "ACPAgent", + "title": "Kind" + } + }, + "type": "object", + "required": ["acp_command", "kind"], + "title": "ACPAgent", + "description": "Agent that delegates to an ACP-compatible subprocess server." + }, + "ACPToolCallEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "agent" + }, + "tool_call_id": { + "type": "string", + "title": "Tool Call Id" + }, + "title": { + "type": "string", + "title": "Title" + }, + "status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Status" + }, + "tool_kind": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Tool Kind" + }, + "raw_input": { + "anyOf": [ + {}, + { + "type": "null" + } + ], + "title": "Raw Input" + }, + "raw_output": { + "anyOf": [ + {}, + { + "type": "null" + } + ], + "title": "Raw Output" + }, + "content": { + "anyOf": [ + { + "items": {}, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Content" + }, + "is_error": { + "type": "boolean", + "title": "Is Error", + "default": false + }, + "kind": { + "type": "string", + "const": "ACPToolCallEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tool_call_id", "title", "kind"], + "title": "ACPToolCallEvent", + "description": "Event representing a tool call executed by an ACP server.\n\nCaptures the tool name, inputs, outputs, and status from ACP\n``ToolCallStart`` / ``ToolCallProgress`` notifications so they can\nbe surfaced in the OpenHands event stream and visualizer.\n\nThis is *not* an ``LLMConvertibleEvent`` — ACP tool calls do not\nparticipate in LLM message conversion." + }, + "APIBasedCritic-Input": { + "properties": { + "server_url": { + "type": "string", + "title": "Server Url", + "description": "Base URL of the vLLM classification service", + "default": "https://llm-proxy.app.all-hands.dev/vllm" + }, + "api_key": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + } + ], + "title": "Api Key", + "description": "API key for authenticating with the vLLM service" + }, + "model_name": { + "type": "string", + "title": "Model Name", + "description": "Name of the model to use", + "default": "critic" + }, + "tokenizer_name": { + "type": "string", + "title": "Tokenizer Name", + "description": "HuggingFace tokenizer name for loading chat template", + "default": "Qwen/Qwen3-4B-Instruct-2507" + }, + "pass_tools_definitions": { + "type": "boolean", + "title": "Pass Tools Definitions", + "description": "Whether to pass tool definitions to the model", + "default": true + }, + "timeout_seconds": { + "type": "number", + "title": "Timeout Seconds", + "description": "Timeout for requests to the model", + "default": 300.0 + }, + "has_success_label": { + "type": "boolean", + "title": "Has Success Label", + "description": "Whether the model predicts success label at index 0", + "default": true + }, + "sentiment_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Sentiment Labels", + "default": ["sentiment_positive", "sentiment_neutral", "sentiment_negative"] + }, + "agent_issue_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Agent Issue Labels", + "default": [ + "misunderstood_intention", + "did_not_follow_instruction", + "insufficient_analysis", + "insufficient_clarification", + "improper_tool_use_or_setup", + "loop_behavior", + "insufficient_testing", + "insufficient_debugging", + "incomplete_implementation", + "file_management_errors", + "scope_creep", + "risky_actions_or_permission", + "other_agent_issue" + ] + }, + "infra_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Infra Labels", + "default": ["infrastructure_external_issue", "infrastructure_agent_caused_issue"] + }, + "user_followup_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "User Followup Labels", + "default": [ + "clarification_or_restatement", + "correction", + "direction_change", + "vcs_update_requests", + "progress_or_scope_concern", + "frustration_or_complaint", + "removal_or_reversion_request", + "other_user_issue" + ] + }, + "sentiment_map": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Sentiment Map", + "default": { + "Positive": "sentiment_positive", + "Neutral": "sentiment_neutral", + "Negative": "sentiment_negative" + } + }, + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } + ], + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." + }, + "issue_threshold": { + "type": "number", + "maximum": 1.0, + "minimum": 0.0, + "title": "Issue Threshold", + "description": "APIBasedCritic-specific probability threshold for agent issue labels that should trigger iterative refinement.", + "default": 0.75 + }, + "kind": { + "type": "string", + "const": "APIBasedCritic", + "title": "Kind" + } + }, + "type": "object", + "required": ["api_key"], + "title": "APIBasedCritic" + }, + "APIBasedCritic-Output": { + "properties": { + "server_url": { + "type": "string", + "title": "Server Url", + "description": "Base URL of the vLLM classification service", + "default": "https://llm-proxy.app.all-hands.dev/vllm" + }, + "api_key": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + } + ], + "title": "Api Key", + "description": "API key for authenticating with the vLLM service" + }, + "model_name": { + "type": "string", + "title": "Model Name", + "description": "Name of the model to use", + "default": "critic" + }, + "tokenizer_name": { + "type": "string", + "title": "Tokenizer Name", + "description": "HuggingFace tokenizer name for loading chat template", + "default": "Qwen/Qwen3-4B-Instruct-2507" + }, + "pass_tools_definitions": { + "type": "boolean", + "title": "Pass Tools Definitions", + "description": "Whether to pass tool definitions to the model", + "default": true + }, + "timeout_seconds": { + "type": "number", + "title": "Timeout Seconds", + "description": "Timeout for requests to the model", + "default": 300.0 + }, + "has_success_label": { + "type": "boolean", + "title": "Has Success Label", + "description": "Whether the model predicts success label at index 0", + "default": true + }, + "sentiment_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Sentiment Labels", + "default": ["sentiment_positive", "sentiment_neutral", "sentiment_negative"] + }, + "agent_issue_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Agent Issue Labels", + "default": [ + "misunderstood_intention", + "did_not_follow_instruction", + "insufficient_analysis", + "insufficient_clarification", + "improper_tool_use_or_setup", + "loop_behavior", + "insufficient_testing", + "insufficient_debugging", + "incomplete_implementation", + "file_management_errors", + "scope_creep", + "risky_actions_or_permission", + "other_agent_issue" + ] + }, + "infra_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Infra Labels", + "default": ["infrastructure_external_issue", "infrastructure_agent_caused_issue"] + }, + "user_followup_labels": { + "items": { + "type": "string" + }, + "type": "array", + "title": "User Followup Labels", + "default": [ + "clarification_or_restatement", + "correction", + "direction_change", + "vcs_update_requests", + "progress_or_scope_concern", + "frustration_or_complaint", + "removal_or_reversion_request", + "other_user_issue" + ] + }, + "sentiment_map": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Sentiment Map", + "default": { + "Positive": "sentiment_positive", + "Neutral": "sentiment_neutral", + "Negative": "sentiment_negative" + } + }, + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } + ], + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." + }, + "issue_threshold": { + "type": "number", + "maximum": 1.0, + "minimum": 0.0, + "title": "Issue Threshold", + "description": "APIBasedCritic-specific probability threshold for agent issue labels that should trigger iterative refinement.", + "default": 0.75 + }, + "kind": { + "type": "string", + "const": "APIBasedCritic", + "title": "Kind" + } + }, + "type": "object", + "required": ["api_key", "kind"], + "title": "APIBasedCritic" + }, + "Action": { + "oneOf": [ + { + "$ref": "#/components/schemas/BrowserActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserClickActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserCloseTabActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserGetContentActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserGetStateActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserGetStorageActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserGoBackActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserListTabsActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserNavigateActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserScrollActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserSetStorageActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserStartRecordingActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserStopRecordingActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserSwitchTabActionWithRisk" + }, + { + "$ref": "#/components/schemas/BrowserTypeActionWithRisk" + }, + { + "$ref": "#/components/schemas/DelegateActionWithRisk" + }, + { + "$ref": "#/components/schemas/EditActionWithRisk" + }, + { + "$ref": "#/components/schemas/FileEditorActionWithRisk" + }, + { + "$ref": "#/components/schemas/FinishActionWithRisk" + }, + { + "$ref": "#/components/schemas/GlobActionWithRisk" + }, + { + "$ref": "#/components/schemas/GrepActionWithRisk" + }, + { + "$ref": "#/components/schemas/InvokeSkillActionWithRisk" + }, + { + "$ref": "#/components/schemas/ListDirectoryActionWithRisk" + }, + { + "$ref": "#/components/schemas/MCPToolActionWithRisk" + }, + { + "$ref": "#/components/schemas/PlanningFileEditorActionWithRisk" + }, + { + "$ref": "#/components/schemas/ReadFileActionWithRisk" + }, + { + "$ref": "#/components/schemas/SwitchLLMActionWithRisk" + }, + { + "$ref": "#/components/schemas/TaskActionWithRisk" + }, + { + "$ref": "#/components/schemas/TaskTrackerActionWithRisk" + }, + { + "$ref": "#/components/schemas/TerminalActionWithRisk" + }, + { + "$ref": "#/components/schemas/ThinkActionWithRisk" + }, + { + "$ref": "#/components/schemas/WriteFileActionWithRisk" + }, + { + "$ref": "#/components/schemas/MCPToolAction" + }, + { + "$ref": "#/components/schemas/FinishAction" + }, + { + "$ref": "#/components/schemas/InvokeSkillAction" + }, + { + "$ref": "#/components/schemas/SwitchLLMAction" + }, + { + "$ref": "#/components/schemas/ThinkAction" + }, + { + "$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" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "abc__BrowserActionWithRisk-Output__1": "#/components/schemas/BrowserActionWithRisk", + "abc__BrowserClickActionWithRisk-Output__1": "#/components/schemas/BrowserClickActionWithRisk", + "abc__BrowserCloseTabActionWithRisk-Output__1": "#/components/schemas/BrowserCloseTabActionWithRisk", + "abc__BrowserGetContentActionWithRisk-Output__1": "#/components/schemas/BrowserGetContentActionWithRisk", + "abc__BrowserGetStateActionWithRisk-Output__1": "#/components/schemas/BrowserGetStateActionWithRisk", + "abc__BrowserGetStorageActionWithRisk-Output__1": "#/components/schemas/BrowserGetStorageActionWithRisk", + "abc__BrowserGoBackActionWithRisk-Output__1": "#/components/schemas/BrowserGoBackActionWithRisk", + "abc__BrowserListTabsActionWithRisk-Output__1": "#/components/schemas/BrowserListTabsActionWithRisk", + "abc__BrowserNavigateActionWithRisk-Output__1": "#/components/schemas/BrowserNavigateActionWithRisk", + "abc__BrowserScrollActionWithRisk-Output__1": "#/components/schemas/BrowserScrollActionWithRisk", + "abc__BrowserSetStorageActionWithRisk-Output__1": "#/components/schemas/BrowserSetStorageActionWithRisk", + "abc__BrowserStartRecordingActionWithRisk-Output__1": "#/components/schemas/BrowserStartRecordingActionWithRisk", + "abc__BrowserStopRecordingActionWithRisk-Output__1": "#/components/schemas/BrowserStopRecordingActionWithRisk", + "abc__BrowserSwitchTabActionWithRisk-Output__1": "#/components/schemas/BrowserSwitchTabActionWithRisk", + "abc__BrowserTypeActionWithRisk-Output__1": "#/components/schemas/BrowserTypeActionWithRisk", + "abc__DelegateActionWithRisk-Output__1": "#/components/schemas/DelegateActionWithRisk", + "abc__EditActionWithRisk-Output__1": "#/components/schemas/EditActionWithRisk", + "abc__FileEditorActionWithRisk-Output__1": "#/components/schemas/FileEditorActionWithRisk", + "abc__FinishActionWithRisk-Output__1": "#/components/schemas/FinishActionWithRisk", + "abc__GlobActionWithRisk-Output__1": "#/components/schemas/GlobActionWithRisk", + "abc__GrepActionWithRisk-Output__1": "#/components/schemas/GrepActionWithRisk", + "abc__InvokeSkillActionWithRisk-Output__1": "#/components/schemas/InvokeSkillActionWithRisk", + "abc__ListDirectoryActionWithRisk-Output__1": "#/components/schemas/ListDirectoryActionWithRisk", + "abc__MCPToolActionWithRisk-Output__1": "#/components/schemas/MCPToolActionWithRisk", + "abc__PlanningFileEditorActionWithRisk-Output__1": "#/components/schemas/PlanningFileEditorActionWithRisk", + "abc__ReadFileActionWithRisk-Output__1": "#/components/schemas/ReadFileActionWithRisk", + "abc__SwitchLLMActionWithRisk-Output__1": "#/components/schemas/SwitchLLMActionWithRisk", + "abc__TaskActionWithRisk-Output__1": "#/components/schemas/TaskActionWithRisk", + "abc__TaskTrackerActionWithRisk-Output__1": "#/components/schemas/TaskTrackerActionWithRisk", + "abc__TerminalActionWithRisk-Output__1": "#/components/schemas/TerminalActionWithRisk", + "abc__ThinkActionWithRisk-Output__1": "#/components/schemas/ThinkActionWithRisk", + "abc__WriteFileActionWithRisk-Output__1": "#/components/schemas/WriteFileActionWithRisk", + "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__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__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" + } + } + }, + "ActionEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "agent" + }, + "thought": { + "items": { + "$ref": "#/components/schemas/TextContent" + }, + "type": "array", + "title": "Thought", + "description": "The thought process of the agent before taking this action" + }, + "reasoning_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Reasoning Content", + "description": "Intermediate reasoning/thinking content from reasoning models" + }, + "thinking_blocks": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/ThinkingBlock" + }, + { + "$ref": "#/components/schemas/RedactedThinkingBlock" + } + ] + }, + "type": "array", + "title": "Thinking Blocks", + "description": "Anthropic thinking blocks from the LLM response" + }, + "responses_reasoning_item": { + "anyOf": [ + { + "$ref": "#/components/schemas/ReasoningItemModel" + }, + { + "type": "null" + } + ], + "description": "OpenAI Responses reasoning item from model output" + }, + "action": { + "anyOf": [ + { + "$ref": "#/components/schemas/Action" + }, + { + "type": "null" + } + ], + "description": "Single tool call returned by LLM (None when non-executable)" + }, + "tool_name": { + "type": "string", + "title": "Tool Name", + "description": "The name of the tool being called" + }, + "tool_call_id": { + "type": "string", + "title": "Tool Call Id", + "description": "The unique id returned by LLM API for this tool call" + }, + "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." + }, + "llm_response_id": { + "type": "string", + "title": "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." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "critic_result": { + "anyOf": [ + { + "$ref": "#/components/schemas/CriticResult" + }, + { + "type": "null" + } + ], + "description": "Optional critic evaluation of this action and preceding history." + }, + "summary": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Summary", + "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'" + }, + "kind": { + "type": "string", + "const": "ActionEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "thought", + "tool_name", + "tool_call_id", + "tool_call", + "llm_response_id", + "kind" + ], + "title": "ActionEvent" + }, + "ActivateProfileResponse": { + "properties": { + "name": { + "type": "string", + "title": "Name" + }, + "message": { + "type": "string", + "title": "Message" + }, + "llm_applied": { + "type": "boolean", + "title": "Llm Applied", + "default": true + } + }, + "type": "object", + "required": ["name", "message"], + "title": "ActivateProfileResponse", + "description": "Response model for profile activation." + }, + "Agent-Input": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Input", + "description": "LLM configuration for the agent.", + "examples": [ + { + "api_key": "your_api_key_here", + "base_url": "https://llm-proxy.eval.all-hands.dev", + "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + } + ] + }, + "tools": { + "items": { + "$ref": "#/components/schemas/Tool-Input" + }, + "type": "array", + "title": "Tools", + "description": "List of tools to initialize for the agent.", + "examples": [ + { + "name": "TerminalTool", + "params": {} + }, + { + "name": "FileEditorTool", + "params": {} + }, + { + "name": "TaskTrackerTool", + "params": {} + } + ] + }, + "mcp_config": { + "additionalProperties": true, + "type": "object", + "title": "Mcp Config", + "description": "Optional MCP configuration dictionary to create MCP tools.", + "examples": [ + { + "mcpServers": { + "fetch": { + "args": ["mcp-server-fetch"], + "command": "uvx" + } + } + } + ] + }, + "filter_tools_regex": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Filter Tools Regex", + "description": "Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added.", + "examples": ["^(?!repomix)(.*)|^repomix.*pack_codebase.*$"] + }, + "include_default_tools": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Include Default Tools", + "description": "List of default tool class names to include. By default, the agent includes 'FinishTool' and 'ThinkTool'. Set to an empty list to disable all default tools, or provide a subset to include only specific ones. Example: include_default_tools=['FinishTool'] to only include FinishTool, or include_default_tools=[] to disable all default tools.", + "examples": [["FinishTool", "ThinkTool"], ["FinishTool"], []] + }, + "agent_context": { + "anyOf": [ + { + "$ref": "#/components/schemas/AgentContext-Input" + }, + { + "type": "null" + } + ], + "description": "Optional AgentContext to initialize the agent with specific context.", + "examples": [ + { + "skills": [ + { + "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + "name": "AGENTS.md", + "type": "repo" + }, + { + "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + "name": "flarglebargle", + "trigger": ["flarglebargle"], + "type": "knowledge" + } + ], + "system_message_suffix": "Always finish your response with the word 'yay!'", + "user_message_prefix": "The first character of your response should be 'I'" + } + ] + }, + "system_prompt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System Prompt", + "description": "Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`.\n\n**Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour." + }, + "system_prompt_filename": { + "type": "string", + "title": "System Prompt Filename", + "description": "System prompt template filename. Can be either:\n- A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_prompt.j2')", + "default": "system_prompt.j2" + }, + "security_policy_filename": { + "type": "string", + "title": "Security Policy Filename", + "description": "Security policy template filename. Can be either:\n- A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_security_policy.j2')\n- Empty string to disable security policy", + "default": "security_policy.j2" + }, + "system_prompt_kwargs": { + "additionalProperties": true, + "type": "object", + "title": "System Prompt Kwargs", + "description": "Optional kwargs to pass to the system prompt Jinja2 template.", + "examples": [ + { + "cli_mode": true + } + ] + }, + "condenser": { + "anyOf": [ + { + "$ref": "#/components/schemas/CondenserBase-Input" + }, + { + "type": "null" + } + ], + "description": "Optional condenser to use for condensing conversation history.", + "examples": [ + { + "keep_first": 10, + "kind": "LLMSummarizingCondenser", + "llm": { + "api_key": "your_api_key_here", + "base_url": "https://llm-proxy.eval.all-hands.dev", + "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + }, + "max_size": 80 + } + ] + }, + "critic": { + "anyOf": [ + { + "$ref": "#/components/schemas/CriticBase-Input" + }, + { + "type": "null" + } + ], + "description": "EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode.", + "examples": [ + { + "kind": "AgentFinishedCritic" + } + ] + }, + "tool_concurrency_limit": { + "type": "integer", + "minimum": 1.0, + "title": "Tool Concurrency Limit", + "description": "Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race.", + "default": 1 + }, + "kind": { + "type": "string", + "const": "Agent", + "title": "Kind" + } + }, + "type": "object", + "required": ["llm"], + "title": "Agent", + "description": "Main agent implementation for OpenHands.\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. Critic-related functionality\nis provided by CriticMixin.\n\nAttributes:\n llm: The language model instance used for reasoning.\n tools: List of tools available to the agent.\n system_prompt: Inline system prompt string. When provided the agent\n uses this text verbatim instead of rendering from a template.\n Mutually exclusive with a non-default ``system_prompt_filename``.\n **Not recommended** unless you know what you are doing (e.g.\n customising agent behaviour for a completely different task) —\n this will override OpenHands' built-in system instructions.\n system_prompt_filename: Jinja2 template filename resolved relative to\n the agent's prompts directory, or an absolute path. Defaults to\n ``\"system_prompt.j2\"``.\n system_prompt_kwargs: Extra kwargs forwarded to the Jinja2 template.\n\nExample:\n ```python\n from openhands.sdk import LLM, Agent, Tool\n from pydantic import SecretStr\n\n llm = LLM(model=\"claude-sonnet-4-20250514\", api_key=SecretStr(\"key\"))\n tools = [Tool(name=\"TerminalTool\"), Tool(name=\"FileEditorTool\")]\n agent = Agent(llm=llm, tools=tools)\n ```\n\n To override the system prompt entirely::\n\n agent = Agent(\n llm=llm,\n tools=tools,\n system_prompt=\"You are a helpful coding assistant.\",\n )" + }, + "Agent-Output": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Output", + "description": "LLM configuration for the agent.", + "examples": [ + { + "api_key": "your_api_key_here", + "base_url": "https://llm-proxy.eval.all-hands.dev", + "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + } + ] + }, + "tools": { + "items": { + "$ref": "#/components/schemas/openhands__sdk__tool__spec__Tool" + }, + "type": "array", + "title": "Tools", + "description": "List of tools to initialize for the agent.", + "examples": [ + { + "name": "TerminalTool", + "params": {} + }, + { + "name": "FileEditorTool", + "params": {} + }, + { + "name": "TaskTrackerTool", + "params": {} + } + ] + }, + "mcp_config": { + "additionalProperties": true, + "type": "object", + "title": "Mcp Config", + "description": "Optional MCP configuration dictionary to create MCP tools.", + "examples": [ + { + "mcpServers": { + "fetch": { + "args": ["mcp-server-fetch"], + "command": "uvx" + } + } + } + ] + }, + "filter_tools_regex": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Filter Tools Regex", + "description": "Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added.", + "examples": ["^(?!repomix)(.*)|^repomix.*pack_codebase.*$"] + }, + "include_default_tools": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Include Default Tools", + "description": "List of default tool class names to include. By default, the agent includes 'FinishTool' and 'ThinkTool'. Set to an empty list to disable all default tools, or provide a subset to include only specific ones. Example: include_default_tools=['FinishTool'] to only include FinishTool, or include_default_tools=[] to disable all default tools.", + "examples": [["FinishTool", "ThinkTool"], ["FinishTool"], []] + }, + "agent_context": { + "anyOf": [ + { + "$ref": "#/components/schemas/AgentContext-Output" + }, + { + "type": "null" + } + ], + "description": "Optional AgentContext to initialize the agent with specific context.", + "examples": [ + { + "skills": [ + { + "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", + "name": "AGENTS.md", + "type": "repo" + }, + { + "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", + "name": "flarglebargle", + "trigger": ["flarglebargle"], + "type": "knowledge" + } + ], + "system_message_suffix": "Always finish your response with the word 'yay!'", + "user_message_prefix": "The first character of your response should be 'I'" + } + ] + }, + "system_prompt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System Prompt", + "description": "Inline system prompt string. When provided, the agent uses this text verbatim as the system message instead of rendering from `system_prompt_filename`. Mutually exclusive with a non-default `system_prompt_filename`.\n\n**Warning**: This is not recommended unless you know what you are doing (e.g. customising agent behaviour for a completely different task). Setting this will override OpenHands' built-in system instructions that govern default agent behaviour." + }, + "system_prompt_filename": { + "type": "string", + "title": "System Prompt Filename", + "description": "System prompt template filename. Can be either:\n- A relative filename (e.g., 'system_prompt.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_prompt.j2')", + "default": "system_prompt.j2" + }, + "security_policy_filename": { + "type": "string", + "title": "Security Policy Filename", + "description": "Security policy template filename. Can be either:\n- A relative filename (e.g., 'security_policy.j2') loaded from the agent's prompts directory\n- An absolute path (e.g., '/path/to/custom_security_policy.j2')\n- Empty string to disable security policy", + "default": "security_policy.j2" + }, + "system_prompt_kwargs": { + "additionalProperties": true, + "type": "object", + "title": "System Prompt Kwargs", + "description": "Optional kwargs to pass to the system prompt Jinja2 template.", + "examples": [ + { + "cli_mode": true + } + ] + }, + "condenser": { + "anyOf": [ + { + "$ref": "#/components/schemas/CondenserBase-Output" + }, + { + "type": "null" + } + ], + "description": "Optional condenser to use for condensing conversation history.", + "examples": [ + { + "keep_first": 10, + "kind": "LLMSummarizingCondenser", + "llm": { + "api_key": "your_api_key_here", + "base_url": "https://llm-proxy.eval.all-hands.dev", + "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" + }, + "max_size": 80 + } + ] + }, + "critic": { + "anyOf": [ + { + "$ref": "#/components/schemas/CriticBase-Output" + }, + { + "type": "null" + } + ], + "description": "EXPERIMENTAL: Optional critic to evaluate agent actions and messages in real-time. API and behavior may change without notice. May impact performance, especially in 'all_actions' mode.", + "examples": [ + { + "kind": "AgentFinishedCritic" + } + ] + }, + "tool_concurrency_limit": { + "type": "integer", + "minimum": 1.0, + "title": "Tool Concurrency Limit", + "description": "Maximum number of tool calls to execute concurrently within a single agent step. Default is 1 (sequential). Values > 1 enable parallel execution; concurrent tools share the conversation object, filesystem, and working directory, so mutations to shared state may race.", + "default": 1 + }, + "kind": { + "type": "string", + "const": "Agent", + "title": "Kind" + } + }, + "type": "object", + "required": ["llm", "kind"], + "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. Critic-related functionality\nis provided by CriticMixin.\n\nAttributes:\n llm: The language model instance used for reasoning.\n tools: List of tools available to the agent.\n system_prompt: Inline system prompt string. When provided the agent\n uses this text verbatim instead of rendering from a template.\n Mutually exclusive with a non-default ``system_prompt_filename``.\n **Not recommended** unless you know what you are doing (e.g.\n customising agent behaviour for a completely different task) —\n this will override OpenHands' built-in system instructions.\n system_prompt_filename: Jinja2 template filename resolved relative to\n the agent's prompts directory, or an absolute path. Defaults to\n ``\"system_prompt.j2\"``.\n system_prompt_kwargs: Extra kwargs forwarded to the Jinja2 template.\n\nExample:\n ```python\n from openhands.sdk import LLM, Agent, Tool\n from pydantic import SecretStr\n\n llm = LLM(model=\"claude-sonnet-4-20250514\", api_key=SecretStr(\"key\"))\n tools = [Tool(name=\"TerminalTool\"), Tool(name=\"FileEditorTool\")]\n agent = Agent(llm=llm, tools=tools)\n ```\n\n To override the system prompt entirely::\n\n agent = Agent(\n llm=llm,\n tools=tools,\n system_prompt=\"You are a helpful coding assistant.\",\n )" + }, + "AgentBase-Input": { + "oneOf": [ + { + "$ref": "#/components/schemas/ACPAgent-Input" + }, + { + "$ref": "#/components/schemas/Agent-Input" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__agent__acp_agent__ACPAgent-Input__1": "#/components/schemas/ACPAgent-Input", + "openhands__sdk__agent__agent__Agent-Input__1": "#/components/schemas/Agent-Input" + } + } + }, + "AgentBase-Output": { + "oneOf": [ + { + "$ref": "#/components/schemas/ACPAgent-Output" + }, + { + "$ref": "#/components/schemas/Agent-Output" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__agent__acp_agent__ACPAgent-Output__1": "#/components/schemas/ACPAgent-Output", + "openhands__sdk__agent__agent__Agent-Output__1": "#/components/schemas/Agent-Output" + } + } + }, + "AgentContext-Input": { + "properties": { + "skills": { + "items": { + "$ref": "#/components/schemas/Skill" + }, + "type": "array", + "title": "Skills", + "description": "List of available skills that can extend the user's input.", + "acp_compatible": true + }, + "system_message_suffix": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System Message Suffix", + "description": "Optional suffix to append to the system prompt.", + "acp_compatible": true + }, + "user_message_suffix": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Message Suffix", + "description": "Optional suffix to append to the user's message.", + "acp_compatible": true + }, + "load_user_skills": { + "type": "boolean", + "title": "Load User Skills", + "description": "Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). ", + "default": false, + "acp_compatible": true + }, + "load_public_skills": { + "type": "boolean", + "title": "Load Public Skills", + "description": "Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/extensions. This allows you to get the latest skills without SDK updates.", + "default": false, + "acp_compatible": true + }, + "marketplace_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Marketplace Path", + "description": "Relative marketplace JSON path within the public skills repository. Set to None to load all public skills without marketplace filtering.", + "default": "marketplaces/default.json", + "acp_compatible": true + }, + "secrets": { + "anyOf": [ + { + "additionalProperties": { + "anyOf": [ + { + "type": "string" + }, + { + "$ref": "#/components/schemas/SecretSource-Input" + } + ] + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Secrets", + "description": "Dictionary mapping secret keys to values or secret sources. Secrets are used for authentication and sensitive data handling. Values can be either strings or SecretSource instances (str | SecretSource).", + "acp_compatible": true + }, + "current_datetime": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Current Datetime", + "description": "Current date and time information to provide to the agent. Can be a datetime object (which will be formatted as ISO 8601) or a pre-formatted string. When provided, this information is included in the system prompt to give the agent awareness of the current time context. Defaults to the current datetime.", + "acp_compatible": true + } + }, + "type": "object", + "title": "AgentContext", + "description": "Central structure for managing prompt extension.\n\nAgentContext unifies all the contextual inputs that shape how the system\nextends and interprets user prompts. It combines both static environment\ndetails and dynamic, user-activated extensions from skills.\n\nSpecifically, it provides:\n- **Repository context / Repo Skills**: Information about the active codebase,\n branches, and repo-specific instructions contributed by repo skills.\n- **Runtime context**: Current execution environment (hosts, working\n directory, secrets, date, etc.).\n- **Conversation instructions**: Optional task- or channel-specific rules\n that constrain or guide the agent’s behavior across the session.\n- **Knowledge Skills**: Extensible components that can be triggered by user input\n to inject knowledge or domain-specific guidance.\n\nTogether, these elements make AgentContext the primary container responsible\nfor assembling, formatting, and injecting all prompt-relevant context into\nLLM interactions." + }, + "AgentContext-Output": { + "properties": { + "skills": { + "items": { + "$ref": "#/components/schemas/Skill" + }, + "type": "array", + "title": "Skills", + "description": "List of available skills that can extend the user's input.", + "acp_compatible": true + }, + "system_message_suffix": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "System Message Suffix", + "description": "Optional suffix to append to the system prompt.", + "acp_compatible": true + }, + "user_message_suffix": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Message Suffix", + "description": "Optional suffix to append to the user's message.", + "acp_compatible": true + }, + "load_user_skills": { + "type": "boolean", + "title": "Load User Skills", + "description": "Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility). ", + "default": false, + "acp_compatible": true + }, + "load_public_skills": { + "type": "boolean", + "title": "Load Public Skills", + "description": "Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/extensions. This allows you to get the latest skills without SDK updates.", + "default": false, + "acp_compatible": true + }, + "marketplace_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Marketplace Path", + "description": "Relative marketplace JSON path within the public skills repository. Set to None to load all public skills without marketplace filtering.", + "default": "marketplaces/default.json", + "acp_compatible": true + }, + "secrets": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Secrets", + "description": "Dictionary mapping secret keys to values or secret sources. Secrets are used for authentication and sensitive data handling. Values can be either strings or SecretSource instances (str | SecretSource).", + "acp_compatible": true + }, + "current_datetime": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Current Datetime", + "description": "Current date and time information to provide to the agent. Can be a datetime object (which will be formatted as ISO 8601) or a pre-formatted string. When provided, this information is included in the system prompt to give the agent awareness of the current time context. Defaults to the current datetime.", + "acp_compatible": true + } + }, + "type": "object", + "title": "AgentContext", + "description": "Central structure for managing prompt extension.\n\nAgentContext unifies all the contextual inputs that shape how the system\nextends and interprets user prompts. It combines both static environment\ndetails and dynamic, user-activated extensions from skills.\n\nSpecifically, it provides:\n- **Repository context / Repo Skills**: Information about the active codebase,\n branches, and repo-specific instructions contributed by repo skills.\n- **Runtime context**: Current execution environment (hosts, working\n directory, secrets, date, etc.).\n- **Conversation instructions**: Optional task- or channel-specific rules\n that constrain or guide the agent’s behavior across the session.\n- **Knowledge Skills**: Extensible components that can be triggered by user input\n to inject knowledge or domain-specific guidance.\n\nTogether, these elements make AgentContext the primary container responsible\nfor assembling, formatting, and injecting all prompt-relevant context into\nLLM interactions." + }, + "AgentDefinition": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "Agent name (from frontmatter or filename)" + }, + "description": { + "type": "string", + "title": "Description", + "description": "Agent description", + "default": "" + }, + "model": { + "type": "string", + "title": "Model", + "description": "Model to use ('inherit' uses parent model)", + "default": "inherit" + }, + "color": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Color", + "description": "Display color for the agent" + }, + "tools": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Tools", + "description": "List of allowed tools for this agent" + }, + "skills": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Skills", + "description": "List of skill names for this agent. Resolved from project/user directories." + }, + "system_prompt": { + "type": "string", + "title": "System Prompt", + "description": "System prompt content", + "default": "" + }, + "source": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Source", + "description": "Source file path for this agent" + }, + "when_to_use_examples": { + "items": { + "type": "string" + }, + "type": "array", + "title": "When To Use Examples", + "description": "Examples of when to use this agent (for triggering)" + }, + "hooks": { + "anyOf": [ + { + "$ref": "#/components/schemas/HookConfig-Input" + }, + { + "type": "null" + } + ], + "description": "Hook configuration for this agent" + }, + "permission_mode": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Permission Mode", + "description": "How the subagent handles permissions. None inherits the parent policy, 'always_confirm' requires confirmation for every action, 'never_confirm' skips all confirmations, 'confirm_risky' only confirms actions above a risk threshold." + }, + "max_iteration_per_run": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Max Iteration Per Run", + "description": "Maximum iterations per run. It must be strictly positive, or None for default." + }, + "mcp_servers": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Mcp Servers", + "description": "MCP server configurations for this agent. Keys are server names, values are server configs with 'command', 'args', etc.", + "examples": [ + { + "fetch": { + "args": ["mcp-server-fetch"], + "command": "uvx" + } + } + ] + }, + "profile_store_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Profile Store Dir", + "description": "Path to the directory where LLM profiles are stored. If None, the default profile store directory is used." + }, + "metadata": { + "additionalProperties": true, + "type": "object", + "title": "Metadata", + "description": "Additional metadata from frontmatter" + } + }, + "type": "object", + "required": ["name"], + "title": "AgentDefinition", + "description": "Agent definition loaded from Markdown file.\n\nAgents are specialized configurations that can be triggered based on\nuser input patterns. They define custom system prompts and tool access." + }, + "AgentErrorEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "agent" + }, + "tool_name": { + "type": "string", + "title": "Tool Name", + "description": "The tool name that this observation is responding to" + }, + "tool_call_id": { + "type": "string", + "title": "Tool Call Id", + "description": "The tool call id that this observation is responding to" + }, + "error": { + "type": "string", + "title": "Error", + "description": "The error message from the scaffold" + }, + "kind": { + "type": "string", + "const": "AgentErrorEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tool_name", "tool_call_id", "error", "kind"], + "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." + }, + "AgentFinishedCritic-Input": { + "properties": { + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } + ], + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." + }, + "kind": { + "type": "string", + "const": "AgentFinishedCritic", + "title": "Kind" + } + }, + "type": "object", + "title": "AgentFinishedCritic", + "description": "Critic that evaluates whether an agent properly finished a task.\n\nThis critic checks two main criteria:\n1. The agent's last action was a FinishAction (proper completion)\n2. The generated git patch is non-empty (actual changes were made)" + }, + "AgentFinishedCritic-Output": { + "properties": { + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } + ], + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." + }, + "kind": { + "type": "string", + "const": "AgentFinishedCritic", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "AgentFinishedCritic", + "description": "Critic that evaluates whether an agent properly finished a task.\n\nThis critic checks two main criteria:\n1. The agent's last action was a FinishAction (proper completion)\n2. The generated git patch is non-empty (actual changes were made)" + }, + "AgentResponseResult": { + "properties": { + "response": { + "type": "string", + "title": "Response", + "description": "The agent's final response text. Extracted from either a FinishAction message or the last agent MessageEvent. Empty string if no final response is available." + } + }, + "type": "object", + "required": ["response"], + "title": "AgentResponseResult", + "description": "The agent's final response for a conversation.\n\nContains the text of the last agent finish message or text response.\nEmpty string if the agent has not produced a final response yet." + }, + "AlwaysConfirm-Input": { + "properties": { + "kind": { + "type": "string", + "const": "AlwaysConfirm", + "title": "Kind" + } + }, + "type": "object", + "title": "AlwaysConfirm" + }, + "AlwaysConfirm-Output": { + "properties": { + "kind": { + "type": "string", + "const": "AlwaysConfirm", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "AlwaysConfirm" + }, + "AskAgentRequest": { + "properties": { + "question": { + "type": "string", + "title": "Question", + "description": "The question to ask the agent" + } + }, + "type": "object", + "required": ["question"], + "title": "AskAgentRequest", + "description": "Payload to ask the agent a simple question." + }, + "AskAgentResponse": { + "properties": { + "response": { + "type": "string", + "title": "Response", + "description": "The agent's response to the question" + } + }, + "type": "object", + "required": ["response"], + "title": "AskAgentResponse", + "description": "Response containing the agent's answer." + }, + "BaseWorkspace": { + "oneOf": [ + { + "$ref": "#/components/schemas/LocalWorkspace-Output" + }, + { + "$ref": "#/components/schemas/RemoteWorkspace" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__workspace__local__LocalWorkspace-Output__1": "#/components/schemas/LocalWorkspace-Output", + "openhands__sdk__workspace__remote__base__RemoteWorkspace-Output__1": "#/components/schemas/RemoteWorkspace" + } + } + }, + "BashCommand": { + "properties": { + "command": { + "type": "string", + "title": "Command", + "description": "The bash command to execute" + }, + "cwd": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cwd", + "description": "The current working directory" + }, + "timeout": { + "type": "integer", + "title": "Timeout", + "description": "The max number of seconds a command may be permitted to run.", + "default": 300 + }, + "id": { + "type": "string", + "title": "Id" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "title": "Timestamp" + }, + "kind": { + "type": "string", + "const": "BashCommand", + "title": "Kind" + } + }, + "type": "object", + "required": ["command", "kind"], + "title": "BashCommand" + }, + "BashError": { + "properties": { + "id": { + "type": "string", + "title": "Id" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "title": "Timestamp" + }, + "code": { + "type": "string", + "title": "Code", + "description": "Code for the error - typically an error type" + }, + "detail": { + "type": "string", + "title": "Detail", + "description": "Details about the error" + }, + "kind": { + "type": "string", + "const": "BashError", + "title": "Kind" + } + }, + "type": "object", + "required": ["code", "detail", "kind"], + "title": "BashError" + }, + "BashEventBase": { + "oneOf": [ + { + "$ref": "#/components/schemas/BashCommand" + }, + { + "$ref": "#/components/schemas/BashError" + }, + { + "$ref": "#/components/schemas/BashOutput" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__agent_server__models__BashCommand-Output__1": "#/components/schemas/BashCommand", + "openhands__agent_server__models__BashError-Output__1": "#/components/schemas/BashError", + "openhands__agent_server__models__BashOutput-Output__1": "#/components/schemas/BashOutput" + } + } + }, + "BashEventPage": { + "properties": { + "items": { + "items": { + "$ref": "#/components/schemas/BashEventBase" + }, + "type": "array", + "title": "Items" + }, + "next_page_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Page Id" + } + }, + "type": "object", + "required": ["items"], + "title": "BashEventPage" + }, + "BashEventSortOrder": { + "type": "string", + "enum": ["TIMESTAMP", "TIMESTAMP_DESC"], + "title": "BashEventSortOrder" + }, + "BashOutput": { + "properties": { + "id": { + "type": "string", + "title": "Id" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "title": "Timestamp" + }, + "command_id": { + "type": "string", + "title": "Command Id" + }, + "order": { + "type": "integer", + "title": "Order", + "description": "The order for this output, sequentially starting with 0", + "default": 0 + }, + "exit_code": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Exit Code", + "description": "Exit code None implies the command is still running." + }, + "stdout": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Stdout", + "description": "The standard output from the command" + }, + "stderr": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Stderr", + "description": "The error output from the command" + }, + "kind": { + "type": "string", + "const": "BashOutput", + "title": "Kind" + } + }, + "type": "object", + "required": ["command_id", "kind"], + "title": "BashOutput", + "description": "Output of a bash command. A single command may have multiple pieces of output\ndepending on how large the output is." + }, + "Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Input" + } + }, + "type": "object", + "required": ["llm"], + "title": "Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post" + }, + "Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post": { + "properties": { + "profile_name": { + "type": "string", + "title": "Profile Name" + } + }, + "type": "object", + "required": ["profile_name"], + "title": "Body_switch_conversation_profile_api_conversations__conversation_id__switch_profile_post" + }, + "Body_upload_file_query_api_file_upload_post": { + "properties": { + "file": { + "type": "string", + "format": "binary", + "title": "File" + } + }, + "type": "object", + "required": ["file"], + "title": "Body_upload_file_query_api_file_upload_post" + }, + "BrowserAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "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." + }, + "BrowserActionWithRisk": { + "properties": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserActionWithRisk" + }, + "BrowserClickAction": { + "properties": { + "index": { + "type": "integer", + "minimum": 0.0, + "title": "Index", + "description": "The index of the element to click (from browser_get_state)" + }, + "new_tab": { + "type": "boolean", + "title": "New Tab", + "description": "Whether to open any resulting navigation in a new tab. Default: False", + "default": false + }, + "kind": { + "type": "string", + "const": "BrowserClickAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["index", "kind"], + "title": "BrowserClickAction", + "description": "Schema for clicking elements." + }, + "BrowserClickActionWithRisk": { + "properties": { + "index": { + "type": "integer", + "minimum": 0.0, + "title": "Index", + "description": "The index of the element to click (from browser_get_state)" + }, + "new_tab": { + "type": "boolean", + "title": "New Tab", + "description": "Whether to open any resulting navigation in a new tab. Default: False", + "default": false + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserClickActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["index", "kind"], + "title": "BrowserClickActionWithRisk" + }, + "BrowserClickTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserClickTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserClickTool", + "description": "Tool for clicking browser elements." + }, + "BrowserCloseTabAction": { + "properties": { + "tab_id": { + "type": "string", + "title": "Tab Id", + "description": "4 Character Tab ID of the tab to close (from browser_list_tabs)" + }, + "kind": { + "type": "string", + "const": "BrowserCloseTabAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tab_id", "kind"], + "title": "BrowserCloseTabAction", + "description": "Schema for closing browser tabs." + }, + "BrowserCloseTabActionWithRisk": { + "properties": { + "tab_id": { + "type": "string", + "title": "Tab Id", + "description": "4 Character Tab ID of the tab to close (from browser_list_tabs)" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserCloseTabActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tab_id", "kind"], + "title": "BrowserCloseTabActionWithRisk" + }, + "BrowserCloseTabTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserCloseTabTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserCloseTabTool", + "description": "Tool for closing browser tabs." + }, + "BrowserGetContentAction": { + "properties": { + "extract_links": { + "type": "boolean", + "title": "Extract Links", + "description": "Whether to include links in the content (default: False)", + "default": false + }, + "start_from_char": { + "type": "integer", + "minimum": 0.0, + "title": "Start From Char", + "description": "Character index to start from in the page content (default: 0)", + "default": 0 + }, + "kind": { + "type": "string", + "const": "BrowserGetContentAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGetContentAction", + "description": "Schema for getting page content in markdown." + }, + "BrowserGetContentActionWithRisk": { + "properties": { + "extract_links": { + "type": "boolean", + "title": "Extract Links", + "description": "Whether to include links in the content (default: False)", + "default": false + }, + "start_from_char": { + "type": "integer", + "minimum": 0.0, + "title": "Start From Char", + "description": "Character index to start from in the page content (default: 0)", + "default": 0 + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserGetContentActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGetContentActionWithRisk" + }, + "BrowserGetContentTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserGetContentTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserGetContentTool", + "description": "Tool for getting page content in markdown." + }, + "BrowserGetStateAction": { + "properties": { + "include_screenshot": { + "type": "boolean", + "title": "Include Screenshot", + "description": "Whether to include a screenshot of the current page. Default: False", + "default": false + }, + "kind": { + "type": "string", + "const": "BrowserGetStateAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGetStateAction", + "description": "Schema for getting browser state." + }, + "BrowserGetStateActionWithRisk": { + "properties": { + "include_screenshot": { + "type": "boolean", + "title": "Include Screenshot", + "description": "Whether to include a screenshot of the current page. Default: False", + "default": false + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserGetStateActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGetStateActionWithRisk" + }, + "BrowserGetStateTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserGetStateTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserGetStateTool", + "description": "Tool for getting browser state." + }, + "BrowserGetStorageAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserGetStorageAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGetStorageAction", + "description": "Schema for getting browser storage (cookies, local storage, session storage)." + }, + "BrowserGetStorageActionWithRisk": { + "properties": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserGetStorageActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGetStorageActionWithRisk" + }, + "BrowserGetStorageTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserGetStorageTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserGetStorageTool", + "description": "Tool for getting browser storage." + }, + "BrowserGoBackAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserGoBackAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGoBackAction", + "description": "Schema for going back in browser history." + }, + "BrowserGoBackActionWithRisk": { + "properties": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserGoBackActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserGoBackActionWithRisk" + }, + "BrowserGoBackTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserGoBackTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserGoBackTool", + "description": "Tool for going back in browser history." + }, + "BrowserListTabsAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserListTabsAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserListTabsAction", + "description": "Schema for listing browser tabs." + }, + "BrowserListTabsActionWithRisk": { + "properties": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserListTabsActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserListTabsActionWithRisk" + }, + "BrowserListTabsTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserListTabsTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserListTabsTool", + "description": "Tool for listing browser tabs." + }, + "BrowserNavigateAction": { + "properties": { + "url": { + "type": "string", + "title": "Url", + "description": "The URL to navigate to" + }, + "new_tab": { + "type": "boolean", + "title": "New Tab", + "description": "Whether to open in a new tab. Default: False", + "default": false + }, + "kind": { + "type": "string", + "const": "BrowserNavigateAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["url", "kind"], + "title": "BrowserNavigateAction", + "description": "Schema for browser navigation." + }, + "BrowserNavigateActionWithRisk": { + "properties": { + "url": { + "type": "string", + "title": "Url", + "description": "The URL to navigate to" + }, + "new_tab": { + "type": "boolean", + "title": "New Tab", + "description": "Whether to open in a new tab. Default: False", + "default": false + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserNavigateActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["url", "kind"], + "title": "BrowserNavigateActionWithRisk" + }, + "BrowserNavigateTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserNavigateTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserNavigateTool", + "description": "Tool for browser navigation." + }, + "BrowserObservation": { + "properties": { + "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 + }, + "screenshot_data": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Screenshot Data", + "description": "Base64 screenshot data if available" + }, + "full_output_save_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Full Output Save Dir", + "description": "Directory where full output files are saved" + }, + "kind": { + "type": "string", + "const": "BrowserObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserObservation", + "description": "Base observation for browser operations." + }, + "BrowserScrollAction": { + "properties": { + "direction": { + "type": "string", + "enum": ["up", "down"], + "title": "Direction", + "description": "Direction to scroll. Options: 'up', 'down'. Default: 'down'", + "default": "down" + }, + "kind": { + "type": "string", + "const": "BrowserScrollAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserScrollAction", + "description": "Schema for scrolling the page." + }, + "BrowserScrollActionWithRisk": { + "properties": { + "direction": { + "type": "string", + "enum": ["up", "down"], + "title": "Direction", + "description": "Direction to scroll. Options: 'up', 'down'. Default: 'down'", + "default": "down" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserScrollActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserScrollActionWithRisk" + }, + "BrowserScrollTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserScrollTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserScrollTool", + "description": "Tool for scrolling the browser page." + }, + "BrowserSetStorageAction": { + "properties": { + "storage_state": { + "additionalProperties": true, + "type": "object", + "title": "Storage State", + "description": "Storage state dictionary containing 'cookies' and 'origins' (from browser_get_storage)" + }, + "kind": { + "type": "string", + "const": "BrowserSetStorageAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["storage_state", "kind"], + "title": "BrowserSetStorageAction", + "description": "Schema for setting browser storage (cookies, local storage, session storage)." + }, + "BrowserSetStorageActionWithRisk": { + "properties": { + "storage_state": { + "additionalProperties": true, + "type": "object", + "title": "Storage State", + "description": "Storage state dictionary containing 'cookies' and 'origins' (from browser_get_storage)" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserSetStorageActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["storage_state", "kind"], + "title": "BrowserSetStorageActionWithRisk" + }, + "BrowserSetStorageTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserSetStorageTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserSetStorageTool", + "description": "Tool for setting browser storage." + }, + "BrowserStartRecordingAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserStartRecordingAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserStartRecordingAction", + "description": "Schema for starting browser session recording." + }, + "BrowserStartRecordingActionWithRisk": { + "properties": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserStartRecordingActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserStartRecordingActionWithRisk" + }, + "BrowserStartRecordingTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserStartRecordingTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserStartRecordingTool", + "description": "Tool for starting browser session recording." + }, + "BrowserStopRecordingAction": { + "properties": { + "kind": { + "type": "string", + "const": "BrowserStopRecordingAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserStopRecordingAction", + "description": "Schema for stopping browser session recording." + }, + "BrowserStopRecordingActionWithRisk": { + "properties": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserStopRecordingActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "BrowserStopRecordingActionWithRisk" + }, + "BrowserStopRecordingTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserStopRecordingTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserStopRecordingTool", + "description": "Tool for stopping browser session recording." + }, + "BrowserSwitchTabAction": { + "properties": { + "tab_id": { + "type": "string", + "title": "Tab Id", + "description": "4 Character Tab ID of the tab to switch to (from browser_list_tabs)" + }, + "kind": { + "type": "string", + "const": "BrowserSwitchTabAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tab_id", "kind"], + "title": "BrowserSwitchTabAction", + "description": "Schema for switching browser tabs." + }, + "BrowserSwitchTabActionWithRisk": { + "properties": { + "tab_id": { + "type": "string", + "title": "Tab Id", + "description": "4 Character Tab ID of the tab to switch to (from browser_list_tabs)" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserSwitchTabActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tab_id", "kind"], + "title": "BrowserSwitchTabActionWithRisk" + }, + "BrowserSwitchTabTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserSwitchTabTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserSwitchTabTool", + "description": "Tool for switching browser tabs." + }, + "BrowserToolSet": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserToolSet", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserToolSet", + "description": "A set of all browser tools.\n\nThis tool set includes all available browser-related tools\n for interacting with web pages.\n\nThe toolset automatically checks for Chromium availability\nwhen created and automatically installs it if missing." + }, + "BrowserTypeAction": { + "properties": { + "index": { + "type": "integer", + "minimum": 0.0, + "title": "Index", + "description": "The index of the input element (from browser_get_state)" + }, + "text": { + "type": "string", + "title": "Text", + "description": "The text to type" + }, + "kind": { + "type": "string", + "const": "BrowserTypeAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["index", "text", "kind"], + "title": "BrowserTypeAction", + "description": "Schema for typing text into elements." + }, + "BrowserTypeActionWithRisk": { + "properties": { + "index": { + "type": "integer", + "minimum": 0.0, + "title": "Index", + "description": "The index of the input element (from browser_get_state)" + }, + "text": { + "type": "string", + "title": "Text", + "description": "The text to type" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "BrowserTypeActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["index", "text", "kind"], + "title": "BrowserTypeActionWithRisk" + }, + "BrowserTypeTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "BrowserTypeTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "BrowserTypeTool", + "description": "Tool for typing text into browser elements." + }, + "CloudProxyRequest": { + "properties": { + "host": { + "type": "string", + "title": "Host", + "description": "Cloud host base URL, e.g. 'https://app.all-hands.dev'. Must match the configured allowlist." + }, + "method": { + "type": "string", + "title": "Method", + "default": "GET" + }, + "path": { + "type": "string", + "title": "Path", + "description": "Path on the cloud host, e.g. '/api/organizations'" + }, + "headers": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Headers", + "description": "Headers to forward, including the Authorization bearer token for the cloud backend." + }, + "body": { + "title": "Body" + }, + "timeout_seconds": { + "type": "number", + "maximum": 60.0, + "minimum": 1.0, + "title": "Timeout Seconds", + "default": 15.0 + } + }, + "type": "object", + "required": ["host", "path"], + "title": "CloudProxyRequest", + "description": "Envelope describing the upstream request to forward." + }, + "CmdOutputMetadata": { + "properties": { + "exit_code": { + "type": "integer", + "title": "Exit Code", + "description": "The exit code of the last executed command.", + "default": -1 + }, + "pid": { + "type": "integer", + "title": "Pid", + "description": "The process ID of the last executed command.", + "default": -1 + }, + "username": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Username", + "description": "The username of the current user." + }, + "hostname": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Hostname", + "description": "The hostname of the machine." + }, + "working_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Working Dir", + "description": "The current working directory." + }, + "py_interpreter_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Py Interpreter Path", + "description": "The path to the current Python interpreter, if any." + }, + "prefix": { + "type": "string", + "title": "Prefix", + "description": "Prefix to add to command output", + "default": "" + }, + "suffix": { + "type": "string", + "title": "Suffix", + "description": "Suffix to add to command output", + "default": "" + } + }, + "type": "object", + "title": "CmdOutputMetadata", + "description": "Additional metadata captured from PS1" + }, + "Condensation": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "environment" + }, + "forgotten_event_ids": { + "items": { + "type": "string" + }, + "type": "array", + "uniqueItems": true, + "title": "Forgotten Event Ids", + "description": "The IDs of the events that are being forgotten (removed from the `View` given to the LLM)." + }, + "summary": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Summary", + "description": "An optional summary of the events being forgotten." + }, + "summary_offset": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Summary Offset", + "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." + }, + "llm_response_id": { + "type": "string", + "title": "Llm Response Id", + "description": "Completion or Response ID of the LLM response that generated this event" + }, + "kind": { + "type": "string", + "const": "Condensation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["llm_response_id", "kind"], + "title": "Condensation", + "description": "This action indicates a condensation of the conversation history is happening." + }, + "CondensationRequest": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "environment" + }, + "kind": { + "type": "string", + "const": "CondensationRequest", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "CondensationRequest", + "description": "This action is used to request a condensation of the conversation history.\n\nAttributes:\n action (str): The action type, namely ActionType.CONDENSATION_REQUEST." + }, + "CondensationSummaryEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "environment" + }, + "summary": { + "type": "string", + "title": "Summary" + }, + "kind": { + "type": "string", + "const": "CondensationSummaryEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["summary", "kind"], + "title": "CondensationSummaryEvent", + "description": "This event represents a summary generated by a condenser." + }, + "CondenserBase-Input": { + "oneOf": [ + { + "$ref": "#/components/schemas/LLMSummarizingCondenser-Input" + }, + { + "$ref": "#/components/schemas/NoOpCondenser-Input" + }, + { + "$ref": "#/components/schemas/PipelineCondenser-Input" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Input__1": "#/components/schemas/LLMSummarizingCondenser-Input", + "openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Input__1": "#/components/schemas/NoOpCondenser-Input", + "openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Input__1": "#/components/schemas/PipelineCondenser-Input" + } + } + }, + "CondenserBase-Output": { + "oneOf": [ + { + "$ref": "#/components/schemas/LLMSummarizingCondenser-Output" + }, + { + "$ref": "#/components/schemas/NoOpCondenser-Output" + }, + { + "$ref": "#/components/schemas/PipelineCondenser-Output" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Output__1": "#/components/schemas/LLMSummarizingCondenser-Output", + "openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Output__1": "#/components/schemas/NoOpCondenser-Output", + "openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Output__1": "#/components/schemas/PipelineCondenser-Output" + } + } + }, + "ConfirmRisky-Input": { + "properties": { + "threshold": { + "$ref": "#/components/schemas/SecurityRisk", + "default": "HIGH" + }, + "confirm_unknown": { + "type": "boolean", + "title": "Confirm Unknown", + "default": true + }, + "kind": { + "type": "string", + "const": "ConfirmRisky", + "title": "Kind" + } + }, + "type": "object", + "title": "ConfirmRisky" + }, + "ConfirmRisky-Output": { + "properties": { + "threshold": { + "$ref": "#/components/schemas/SecurityRisk", + "default": "HIGH" + }, + "confirm_unknown": { + "type": "boolean", + "title": "Confirm Unknown", + "default": true + }, + "kind": { + "type": "string", + "const": "ConfirmRisky", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "ConfirmRisky" + }, + "ConfirmationPolicyBase-Input": { + "oneOf": [ + { + "$ref": "#/components/schemas/AlwaysConfirm-Input" + }, + { + "$ref": "#/components/schemas/ConfirmRisky-Input" + }, + { + "$ref": "#/components/schemas/NeverConfirm-Input" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__security__confirmation_policy__AlwaysConfirm-Input__1": "#/components/schemas/AlwaysConfirm-Input", + "openhands__sdk__security__confirmation_policy__ConfirmRisky-Input__1": "#/components/schemas/ConfirmRisky-Input", + "openhands__sdk__security__confirmation_policy__NeverConfirm-Input__1": "#/components/schemas/NeverConfirm-Input" + } + } + }, + "ConfirmationPolicyBase-Output": { + "oneOf": [ + { + "$ref": "#/components/schemas/AlwaysConfirm-Output" + }, + { + "$ref": "#/components/schemas/ConfirmRisky-Output" + }, + { + "$ref": "#/components/schemas/NeverConfirm-Output" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__security__confirmation_policy__AlwaysConfirm-Output__1": "#/components/schemas/AlwaysConfirm-Output", + "openhands__sdk__security__confirmation_policy__ConfirmRisky-Output__1": "#/components/schemas/ConfirmRisky-Output", + "openhands__sdk__security__confirmation_policy__NeverConfirm-Output__1": "#/components/schemas/NeverConfirm-Output" + } + } + }, + "ConfirmationResponseRequest": { + "properties": { + "accept": { + "type": "boolean", + "title": "Accept" + }, + "reason": { + "type": "string", + "title": "Reason", + "default": "User rejected the action." + } + }, + "type": "object", + "required": ["accept"], + "title": "ConfirmationResponseRequest", + "description": "Payload to accept or reject a pending action." + }, + "ConversationErrorEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "description": "The source of this event" + }, + "code": { + "type": "string", + "title": "Code", + "description": "Code for the error - typically a type" + }, + "detail": { + "type": "string", + "title": "Detail", + "description": "Details about the error" + }, + "kind": { + "type": "string", + "const": "ConversationErrorEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["source", "code", "detail", "kind"], + "title": "ConversationErrorEvent", + "description": "Conversation-level failure that is NOT sent back to the LLM.\n\nThis event is emitted by the conversation runtime when an unexpected\nexception bubbles up and prevents the run loop from continuing. It is\nintended for client applications (e.g., UIs) to present a top-level error\nstate, and for orchestration to react. It is not an observation and it is\nnot LLM-convertible.\n\nDifferences from AgentErrorEvent:\n- Not tied to any tool_name/tool_call_id (AgentErrorEvent is a tool\n observation).\n- Typically source='environment' and the run loop moves to an ERROR state,\n while AgentErrorEvent has source='agent' and the conversation can\n continue." + }, + "ConversationExecutionStatus": { + "type": "string", + "enum": [ + "idle", + "running", + "paused", + "waiting_for_confirmation", + "finished", + "error", + "stuck", + "deleting" + ], + "title": "ConversationExecutionStatus", + "description": "Enum representing the current execution state of the conversation." + }, + "ConversationInfo": { + "properties": { + "id": { + "type": "string", + "format": "uuid", + "title": "Id", + "description": "Unique conversation ID" + }, + "workspace": { + "$ref": "#/components/schemas/BaseWorkspace", + "description": "Workspace used by the agent to execute commands and read/write files. Not the process working directory." + }, + "persistence_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Persistence Dir", + "description": "Directory for persisting conversation state and events. If None, conversation will not be persisted.", + "default": "workspace/conversations" + }, + "max_iterations": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Max Iterations", + "description": "Maximum number of iterations the agent can perform in a single run.", + "default": 500 + }, + "stuck_detection": { + "type": "boolean", + "title": "Stuck Detection", + "description": "Whether to enable stuck detection for the agent.", + "default": true + }, + "execution_status": { + "$ref": "#/components/schemas/ConversationExecutionStatus", + "default": "idle" + }, + "confirmation_policy": { + "$ref": "#/components/schemas/ConfirmationPolicyBase-Output", + "default": { + "kind": "NeverConfirm" + } + }, + "security_analyzer": { + "anyOf": [ + { + "$ref": "#/components/schemas/SecurityAnalyzerBase-Output" + }, + { + "type": "null" + } + ], + "description": "Optional security analyzer to evaluate action risks." + }, + "activated_knowledge_skills": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Activated Knowledge Skills", + "description": "List of activated knowledge skills name" + }, + "invoked_skills": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Invoked Skills", + "description": "Names of progressive-disclosure skills explicitly invoked via the `invoke_skill` tool." + }, + "blocked_actions": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Blocked Actions", + "description": "Actions blocked by PreToolUse hooks, keyed by action ID" + }, + "blocked_messages": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Blocked Messages", + "description": "Messages blocked by UserPromptSubmit hooks, keyed by message ID" + }, + "last_user_message_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last User Message Id", + "description": "Most recent user MessageEvent id for hook block checks. Updated when user messages are emitted so Agent.step can pop blocked_messages without scanning the event log. If None, hook-blocked checks are skipped (legacy conversations)." + }, + "stats": { + "$ref": "#/components/schemas/ConversationStats", + "description": "Conversation statistics for tracking LLM metrics" + }, + "secret_registry": { + "$ref": "#/components/schemas/SecretRegistry", + "description": "Registry for handling secrets and sensitive data" + }, + "agent_state": { + "additionalProperties": true, + "type": "object", + "title": "Agent State", + "description": "Dictionary for agent-specific runtime state that persists across iterations." + }, + "hook_config": { + "anyOf": [ + { + "$ref": "#/components/schemas/HookConfig-Output" + }, + { + "type": "null" + } + ], + "description": "Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks." + }, + "title": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title", + "description": "User-defined title for the conversation" + }, + "metrics": { + "anyOf": [ + { + "$ref": "#/components/schemas/MetricsSnapshot" + }, + { + "type": "null" + } + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "title": "Created At" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "title": "Updated At" + }, + "tags": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Tags", + "description": "Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters." + }, + "agent": { + "$ref": "#/components/schemas/AgentBase-Output", + "description": "The agent running in the conversation." + } + }, + "type": "object", + "required": ["id", "workspace", "agent"], + "title": "ConversationInfo", + "description": "Information about a conversation running locally without a Runtime sandbox." + }, + "ConversationPage": { + "properties": { + "items": { + "items": { + "$ref": "#/components/schemas/ConversationInfo" + }, + "type": "array", + "title": "Items" + }, + "next_page_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Page Id" + } + }, + "type": "object", + "required": ["items"], + "title": "ConversationPage" + }, + "ConversationSortOrder": { + "type": "string", + "enum": ["CREATED_AT", "UPDATED_AT", "CREATED_AT_DESC", "UPDATED_AT_DESC"], + "title": "ConversationSortOrder", + "description": "Enum for conversation sorting options." + }, + "ConversationStateUpdateEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "environment" + }, + "key": { + "type": "string", + "title": "Key", + "description": "Unique key for this state update event" + }, + "value": { + "title": "Value", + "description": "Serialized conversation state updates" + }, + "kind": { + "type": "string", + "const": "ConversationStateUpdateEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "ConversationStateUpdateEvent", + "description": "Event that contains conversation state updates.\n\nThis event is sent via websocket whenever the conversation state changes,\nallowing remote clients to stay in sync without making REST API calls.\n\nAll fields are serialized versions of the corresponding ConversationState fields\nto ensure compatibility with websocket transmission." + }, + "ConversationStats": { + "additionalProperties": true, + "type": "object" + }, + "Cost": { + "properties": { + "model": { + "type": "string", + "title": "Model" + }, + "cost": { + "type": "number", + "minimum": 0.0, + "title": "Cost", + "description": "Cost must be non-negative" + }, + "timestamp": { + "type": "number", + "title": "Timestamp" + } + }, + "type": "object", + "required": ["model", "cost"], + "title": "Cost" + }, + "CriticBase-Input": { + "oneOf": [ + { + "$ref": "#/components/schemas/AgentFinishedCritic-Input" + }, + { + "$ref": "#/components/schemas/APIBasedCritic-Input" + }, + { + "$ref": "#/components/schemas/EmptyPatchCritic-Input" + }, + { + "$ref": "#/components/schemas/PassCritic-Input" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__critic__impl__agent_finished__AgentFinishedCritic-Input__1": "#/components/schemas/AgentFinishedCritic-Input", + "openhands__sdk__critic__impl__api__critic__APIBasedCritic-Input__1": "#/components/schemas/APIBasedCritic-Input", + "openhands__sdk__critic__impl__empty_patch__EmptyPatchCritic-Input__1": "#/components/schemas/EmptyPatchCritic-Input", + "openhands__sdk__critic__impl__pass_critic__PassCritic-Input__1": "#/components/schemas/PassCritic-Input" + } + } + }, + "CriticBase-Output": { + "oneOf": [ + { + "$ref": "#/components/schemas/AgentFinishedCritic-Output" + }, + { + "$ref": "#/components/schemas/APIBasedCritic-Output" + }, + { + "$ref": "#/components/schemas/EmptyPatchCritic-Output" + }, + { + "$ref": "#/components/schemas/PassCritic-Output" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__critic__impl__agent_finished__AgentFinishedCritic-Output__1": "#/components/schemas/AgentFinishedCritic-Output", + "openhands__sdk__critic__impl__api__critic__APIBasedCritic-Output__1": "#/components/schemas/APIBasedCritic-Output", + "openhands__sdk__critic__impl__empty_patch__EmptyPatchCritic-Output__1": "#/components/schemas/EmptyPatchCritic-Output", + "openhands__sdk__critic__impl__pass_critic__PassCritic-Output__1": "#/components/schemas/PassCritic-Output" + } + } + }, + "CriticResult": { + "properties": { + "score": { + "type": "number", + "maximum": 1.0, + "minimum": 0.0, + "title": "Score", + "description": "A predicted probability of success between 0 and 1." + }, + "message": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Message", + "description": "An optional message explaining the score." + }, + "metadata": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Metadata", + "description": "Optional metadata about the critic evaluation. Can include event_ids and categorized_features for visualization." + } + }, + "type": "object", + "required": ["score", "message"], + "title": "CriticResult", + "description": "A critic result is a score and a message." + }, + "DelegateAction": { + "properties": { + "command": { + "type": "string", + "enum": ["spawn", "delegate"], + "title": "Command", + "description": "The commands to run. Allowed options are: `spawn`, `delegate`." + }, + "ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Ids", + "description": "Required parameter of `spawn` command. List of identifiers to initialize sub-agents with." + }, + "agent_types": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Agent Types", + "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." + }, + "tasks": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Tasks", + "description": "Required parameter of `delegate` command. Dictionary mapping sub-agent identifiers to task descriptions." + }, + "kind": { + "type": "string", + "const": "DelegateAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "kind"], + "title": "DelegateAction", + "description": "Schema for delegation operations." + }, + "DelegateActionWithRisk": { + "properties": { + "command": { + "type": "string", + "enum": ["spawn", "delegate"], + "title": "Command", + "description": "The commands to run. Allowed options are: `spawn`, `delegate`." + }, + "ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Ids", + "description": "Required parameter of `spawn` command. List of identifiers to initialize sub-agents with." + }, + "agent_types": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Agent Types", + "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." + }, + "tasks": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Tasks", + "description": "Required parameter of `delegate` command. Dictionary mapping sub-agent identifiers to task descriptions." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "DelegateActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "kind"], + "title": "DelegateActionWithRisk" + }, + "DelegateObservation": { + "properties": { + "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": ["spawn", "delegate"], + "title": "Command", + "description": "The command that was executed" + }, + "kind": { + "type": "string", + "const": "DelegateObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "kind"], + "title": "DelegateObservation", + "description": "Observation from delegation operations." + }, + "DelegateTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "DelegateTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "DelegateTool", + "description": "A ToolDefinition subclass that automatically initializes a DelegateExecutor.\n\n.. deprecated:: 1.16.0\n DelegateTool is deprecated in favor of TaskToolSet. Use TaskToolSet for\n sub-agent delegation. DelegateTool will be removed in version 1.23.0." + }, + "DesktopUrlResponse": { + "properties": { + "url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Url" + } + }, + "type": "object", + "required": ["url"], + "title": "DesktopUrlResponse", + "description": "Response model for Desktop URL." + }, + "EditAction": { + "properties": { + "file_path": { + "type": "string", + "title": "File Path", + "description": "The path to the file to modify." + }, + "old_string": { + "type": "string", + "title": "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." + }, + "new_string": { + "type": "string", + "title": "New String", + "description": "The text to replace it with." + }, + "expected_replacements": { + "type": "integer", + "minimum": 0.0, + "title": "Expected Replacements", + "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.", + "default": 1 + }, + "kind": { + "type": "string", + "const": "EditAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["file_path", "old_string", "new_string", "kind"], + "title": "EditAction", + "description": "Schema for edit operation." + }, + "EditActionWithRisk": { + "properties": { + "file_path": { + "type": "string", + "title": "File Path", + "description": "The path to the file to modify." + }, + "old_string": { + "type": "string", + "title": "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." + }, + "new_string": { + "type": "string", + "title": "New String", + "description": "The text to replace it with." + }, + "expected_replacements": { + "type": "integer", + "minimum": 0.0, + "title": "Expected Replacements", + "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.", + "default": 1 + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "EditActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["file_path", "old_string", "new_string", "kind"], + "title": "EditActionWithRisk" + }, + "EditObservation": { + "properties": { + "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 + }, + "file_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "File Path", + "description": "The file path that was edited." + }, + "is_new_file": { + "type": "boolean", + "title": "Is New File", + "description": "Whether a new file was created.", + "default": false + }, + "replacements_made": { + "type": "integer", + "title": "Replacements Made", + "description": "Number of replacements actually made.", + "default": 0 + }, + "old_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Old Content", + "description": "The content before the edit." + }, + "new_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "New Content", + "description": "The content after the edit." + }, + "kind": { + "type": "string", + "const": "EditObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "EditObservation", + "description": "Observation from editing a file." + }, + "EditTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "EditTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "EditTool", + "description": "Tool for editing files via find/replace." + }, + "EmptyPatchCritic-Input": { + "properties": { + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } + ], + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." + }, + "kind": { + "type": "string", + "const": "EmptyPatchCritic", + "title": "Kind" + } + }, + "type": "object", + "title": "EmptyPatchCritic", + "description": "Critic that only evaluates whether a git patch is non-empty.\n\nThis critic checks only one criterion:\n- The generated git patch is non-empty (actual changes were made)\n\nUnlike AgentFinishedCritic, this critic does not check for proper\nagent completion with FinishAction." + }, + "EmptyPatchCritic-Output": { + "properties": { + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } + ], + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." + }, + "kind": { + "type": "string", + "const": "EmptyPatchCritic", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "EmptyPatchCritic", + "description": "Critic that only evaluates whether a git patch is non-empty.\n\nThis critic checks only one criterion:\n- The generated git patch is non-empty (actual changes were made)\n\nUnlike AgentFinishedCritic, this critic does not check for proper\nagent completion with FinishAction." + }, + "EnsembleSecurityAnalyzer-Input": { + "properties": { + "analyzers": { + "items": { + "$ref": "#/components/schemas/SecurityAnalyzerBase-Input" + }, + "type": "array", + "minItems": 1, + "title": "Analyzers", + "description": "Analyzers whose assessments are combined via max-severity" + }, + "propagate_unknown": { + "type": "boolean", + "title": "Propagate Unknown", + "description": "When True, any child returning UNKNOWN causes the ensemble to return UNKNOWN. When False (default), UNKNOWN is filtered out if any child returns a concrete level.", + "default": false + }, + "kind": { + "type": "string", + "const": "EnsembleSecurityAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "required": ["analyzers"], + "title": "EnsembleSecurityAnalyzer", + "description": "Wire multiple analyzers together and take the worst-case risk.\n\nUse this as the top-level analyzer you set on a conversation. It\ncalls each child analyzer, collects their risk assessments, and\nreturns the highest concrete risk. It does not perform any detection,\nextraction, or normalization of its own.\n\nHow UNKNOWN works (default, ``propagate_unknown=False``): if *all*\nchildren return UNKNOWN, the ensemble returns UNKNOWN (which\n``ConfirmRisky`` confirms by default). If any child returns a\nconcrete level, UNKNOWN results are filtered out and the highest\nconcrete level wins.\n\nWith ``propagate_unknown=True``: if *any* child returns UNKNOWN, the\nensemble returns UNKNOWN regardless of other results. Use this in\nstricter environments where incomplete assessment should trigger\nconfirmation.\n\nIf a child analyzer raises an exception, it contributes HIGH\n(fail-closed, logged). This prevents a broken analyzer from silently\ndegrading safety.\n\nExample::\n\n from openhands.sdk.security import (\n EnsembleSecurityAnalyzer,\n PatternSecurityAnalyzer,\n PolicyRailSecurityAnalyzer,\n ConfirmRisky,\n SecurityRisk,\n )\n\n analyzer = EnsembleSecurityAnalyzer(\n analyzers=[\n PolicyRailSecurityAnalyzer(),\n PatternSecurityAnalyzer(),\n ]\n )\n policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM)" + }, + "EnsembleSecurityAnalyzer-Output": { + "properties": { + "analyzers": { + "items": { + "$ref": "#/components/schemas/SecurityAnalyzerBase-Output" + }, + "type": "array", + "minItems": 1, + "title": "Analyzers", + "description": "Analyzers whose assessments are combined via max-severity" + }, + "propagate_unknown": { + "type": "boolean", + "title": "Propagate Unknown", + "description": "When True, any child returning UNKNOWN causes the ensemble to return UNKNOWN. When False (default), UNKNOWN is filtered out if any child returns a concrete level.", + "default": false + }, + "kind": { + "type": "string", + "const": "EnsembleSecurityAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "required": ["analyzers", "kind"], + "title": "EnsembleSecurityAnalyzer", + "description": "Wire multiple analyzers together and take the worst-case risk.\n\nUse this as the top-level analyzer you set on a conversation. It\ncalls each child analyzer, collects their risk assessments, and\nreturns the highest concrete risk. It does not perform any detection,\nextraction, or normalization of its own.\n\nHow UNKNOWN works (default, ``propagate_unknown=False``): if *all*\nchildren return UNKNOWN, the ensemble returns UNKNOWN (which\n``ConfirmRisky`` confirms by default). If any child returns a\nconcrete level, UNKNOWN results are filtered out and the highest\nconcrete level wins.\n\nWith ``propagate_unknown=True``: if *any* child returns UNKNOWN, the\nensemble returns UNKNOWN regardless of other results. Use this in\nstricter environments where incomplete assessment should trigger\nconfirmation.\n\nIf a child analyzer raises an exception, it contributes HIGH\n(fail-closed, logged). This prevents a broken analyzer from silently\ndegrading safety.\n\nExample::\n\n from openhands.sdk.security import (\n EnsembleSecurityAnalyzer,\n PatternSecurityAnalyzer,\n PolicyRailSecurityAnalyzer,\n ConfirmRisky,\n SecurityRisk,\n )\n\n analyzer = EnsembleSecurityAnalyzer(\n analyzers=[\n PolicyRailSecurityAnalyzer(),\n PatternSecurityAnalyzer(),\n ]\n )\n policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM)" + }, + "Event": { + "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/PauseEvent" + } + ], + "discriminator": { + "propertyName": "kind", + "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__PauseEvent-Output__1": "#/components/schemas/PauseEvent" + } + } + }, + "EventPage": { + "properties": { + "items": { + "items": { + "$ref": "#/components/schemas/Event" + }, + "type": "array", + "title": "Items" + }, + "next_page_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Page Id" + } + }, + "type": "object", + "required": ["items"], + "title": "EventPage" + }, + "EventSortOrder": { + "type": "string", + "enum": ["TIMESTAMP", "TIMESTAMP_DESC"], + "title": "EventSortOrder", + "description": "Enum for event sorting options." + }, + "ExecuteBashRequest": { + "properties": { + "command": { + "type": "string", + "title": "Command", + "description": "The bash command to execute" + }, + "cwd": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cwd", + "description": "The current working directory" + }, + "timeout": { + "type": "integer", + "title": "Timeout", + "description": "The max number of seconds a command may be permitted to run.", + "default": 300 + } + }, + "type": "object", + "required": ["command"], + "title": "ExecuteBashRequest" + }, + "ExposedUrl": { + "properties": { + "name": { + "type": "string", + "title": "Name" + }, + "url": { + "type": "string", + "title": "Url" + }, + "port": { + "type": "integer", + "title": "Port" + } + }, + "type": "object", + "required": ["name", "url", "port"], + "title": "ExposedUrl", + "description": "Represents an exposed URL from the sandbox." + }, + "FallbackStrategy": { + "properties": { + "fallback_llms": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Fallback Llms", + "description": "Ordered list of LLM profile names to try on transient failure." + }, + "profile_store_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "path" + }, + { + "type": "null" + } + ], + "title": "Profile Store Dir", + "description": "Path to directory containing profiles. If not specified, defaults to `.openhands/profiles`." + } + }, + "type": "object", + "required": ["fallback_llms"], + "title": "FallbackStrategy", + "description": "Encapsulates fallback behavior for LLM calls.\n\nWhen the primary LLM fails with a transient error (after retries),\nthis strategy tries alternate LLMs loaded from LLMProfileStore profiles.\nFallback is per-call: each new request starts with the primary model." + }, + "FileBrowserEntry": { + "properties": { + "label": { + "type": "string", + "title": "Label" + }, + "path": { + "type": "string", + "title": "Path" + } + }, + "type": "object", + "required": ["label", "path"], + "title": "FileBrowserEntry" + }, + "FileEditorAction": { + "properties": { + "command": { + "type": "string", + "enum": ["view", "create", "str_replace", "insert", "undo_edit"], + "title": "Command", + "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." + }, + "path": { + "type": "string", + "title": "Path", + "description": "Absolute path to file or directory." + }, + "file_text": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "File Text", + "description": "Required parameter of `create` command, with the content of the file to be created." + }, + "old_str": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Old Str", + "description": "Required parameter of `str_replace` command containing the string in `path` to replace." + }, + "new_str": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "New Str", + "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." + }, + "insert_line": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Insert Line", + "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`." + }, + "view_range": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "View Range", + "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." + }, + "kind": { + "type": "string", + "const": "FileEditorAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "path", "kind"], + "title": "FileEditorAction", + "description": "Schema for file editor operations." + }, + "FileEditorActionWithRisk": { + "properties": { + "command": { + "type": "string", + "enum": ["view", "create", "str_replace", "insert", "undo_edit"], + "title": "Command", + "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." + }, + "path": { + "type": "string", + "title": "Path", + "description": "Absolute path to file or directory." + }, + "file_text": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "File Text", + "description": "Required parameter of `create` command, with the content of the file to be created." + }, + "old_str": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Old Str", + "description": "Required parameter of `str_replace` command containing the string in `path` to replace." + }, + "new_str": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "New Str", + "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." + }, + "insert_line": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Insert Line", + "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`." + }, + "view_range": { + "anyOf": [ + { + "items": { + "type": "integer" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "View Range", + "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." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "FileEditorActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "path", "kind"], + "title": "FileEditorActionWithRisk" + }, + "FileEditorObservation": { + "properties": { + "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": ["view", "create", "str_replace", "insert", "undo_edit"], + "title": "Command", + "description": "The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`." + }, + "path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Path", + "description": "The file path that was edited." + }, + "prev_exist": { + "type": "boolean", + "title": "Prev Exist", + "description": "Indicates if the file previously existed. If not, it was created.", + "default": true + }, + "old_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Old Content", + "description": "The content of the file before the edit." + }, + "new_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "New Content", + "description": "The content of the file after the edit." + }, + "kind": { + "type": "string", + "const": "FileEditorObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "kind"], + "title": "FileEditorObservation", + "description": "A ToolResult that can be rendered as a CLI output." + }, + "FileEditorTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "FileEditorTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "FileEditorTool", + "description": "A ToolDefinition subclass that automatically initializes a FileEditorExecutor." + }, + "FileEntry": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "Name of the file or directory" + }, + "path": { + "type": "string", + "title": "Path", + "description": "Absolute path to the file or directory" + }, + "is_directory": { + "type": "boolean", + "title": "Is Directory", + "description": "Whether this entry is a directory" + }, + "size": { + "type": "integer", + "title": "Size", + "description": "Size of the file in bytes (0 for directories)" + }, + "modified_time": { + "type": "string", + "format": "date-time", + "title": "Modified Time", + "description": "Last modified timestamp" + } + }, + "type": "object", + "required": ["name", "path", "is_directory", "size", "modified_time"], + "title": "FileEntry", + "description": "Information about a file or directory." + }, + "FinishAction": { + "properties": { + "message": { + "type": "string", + "title": "Message", + "description": "Final message to send to the user." + }, + "kind": { + "type": "string", + "const": "FinishAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["message", "kind"], + "title": "FinishAction" + }, + "FinishActionWithRisk": { + "properties": { + "message": { + "type": "string", + "title": "Message", + "description": "Final message to send to the user." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "FinishActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["message", "kind"], + "title": "FinishActionWithRisk" + }, + "FinishObservation": { + "properties": { + "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 + }, + "kind": { + "type": "string", + "const": "FinishObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "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." + }, + "FinishTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "FinishTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "FinishTool", + "description": "Tool for signaling the completion of a task or conversation." + }, + "ForkConversationRequest": { + "properties": { + "id": { + "anyOf": [ + { + "type": "string", + "format": "uuid" + }, + { + "type": "null" + } + ], + "title": "Id", + "description": "ID for the forked conversation (auto-generated if null)" + }, + "title": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ], + "title": "Title", + "description": "Optional title for the forked conversation" + }, + "tags": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Tags", + "description": "Optional tags for the forked conversation. Keys must be lowercase alphanumeric." + }, + "reset_metrics": { + "type": "boolean", + "title": "Reset Metrics", + "description": "If true, cost/token stats start fresh on the fork. If false, metrics are copied from the source.", + "default": true + } + }, + "type": "object", + "title": "ForkConversationRequest", + "description": "Payload to fork a conversation." + }, + "GitChange": { + "properties": { + "status": { + "$ref": "#/components/schemas/GitChangeStatus" + }, + "path": { + "type": "string", + "format": "path", + "title": "Path" + } + }, + "type": "object", + "required": ["status", "path"], + "title": "GitChange" + }, + "GitChangeStatus": { + "type": "string", + "enum": ["MOVED", "ADDED", "DELETED", "UPDATED"], + "title": "GitChangeStatus" + }, + "GitDiff": { + "properties": { + "modified": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Modified" + }, + "original": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Original" + } + }, + "type": "object", + "required": ["modified", "original"], + "title": "GitDiff" + }, + "GlobAction": { + "properties": { + "pattern": { + "type": "string", + "title": "Pattern", + "description": "The glob pattern to match files (e.g., \"**/*.js\", \"src/**/*.ts\")" + }, + "path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Path", + "description": "The directory (absolute path) to search in. Defaults to the current working directory." + }, + "kind": { + "type": "string", + "const": "GlobAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["pattern", "kind"], + "title": "GlobAction", + "description": "Schema for glob pattern matching operations." + }, + "GlobActionWithRisk": { + "properties": { + "pattern": { + "type": "string", + "title": "Pattern", + "description": "The glob pattern to match files (e.g., \"**/*.js\", \"src/**/*.ts\")" + }, + "path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Path", + "description": "The directory (absolute path) to search in. Defaults to the current working directory." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "GlobActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["pattern", "kind"], + "title": "GlobActionWithRisk" + }, + "GlobObservation": { + "properties": { + "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 + }, + "files": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Files", + "description": "List of matching file paths sorted by modification time" + }, + "pattern": { + "type": "string", + "title": "Pattern", + "description": "The glob pattern that was used" + }, + "search_path": { + "type": "string", + "title": "Search Path", + "description": "The directory that was searched" + }, + "truncated": { + "type": "boolean", + "title": "Truncated", + "description": "Whether results were truncated to 100 files", + "default": false + }, + "kind": { + "type": "string", + "const": "GlobObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["files", "pattern", "search_path", "kind"], + "title": "GlobObservation", + "description": "Observation from glob pattern matching operations." + }, + "GlobTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "GlobTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "GlobTool", + "description": "A ToolDefinition subclass that automatically initializes a GlobExecutor." + }, + "GraySwanAnalyzer-Input": { + "properties": { + "history_limit": { + "type": "integer", + "title": "History Limit", + "description": "Number of recent events to include as context", + "default": 20 + }, + "max_message_chars": { + "type": "integer", + "title": "Max Message Chars", + "description": "Max characters for conversation processing", + "default": 30000 + }, + "timeout": { + "type": "number", + "title": "Timeout", + "description": "Request timeout in seconds", + "default": 30.0 + }, + "low_threshold": { + "type": "number", + "title": "Low Threshold", + "description": "Risk threshold for LOW classification (score <= threshold)", + "default": 0.3 + }, + "medium_threshold": { + "type": "number", + "title": "Medium Threshold", + "description": "Risk threshold for MEDIUM classification (score <= threshold)", + "default": 0.7 + }, + "api_url": { + "type": "string", + "title": "Api Url", + "description": "GraySwan Cygnal API endpoint", + "default": "https://api.grayswan.ai/cygnal/monitor" + }, + "api_key": { + "anyOf": [ + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Api Key", + "description": "GraySwan API key (via GRAYSWAN_API_KEY env var)" + }, + "policy_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Policy Id", + "description": "GraySwan policy ID (via GRAYSWAN_POLICY_ID env var)" + }, + "kind": { + "type": "string", + "const": "GraySwanAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "title": "GraySwanAnalyzer", + "description": "Security analyzer using GraySwan's Cygnal API for AI safety monitoring.\n\nThis analyzer sends conversation history and pending actions to the GraySwan\nCygnal API for security analysis. The API returns a violation score which is\nmapped to SecurityRisk levels.\n\nEnvironment Variables:\n GRAYSWAN_API_KEY: Required API key for GraySwan authentication\n GRAYSWAN_POLICY_ID: Optional policy ID for custom GraySwan policy\n\nExample:\n >>> from openhands.sdk.security.grayswan import GraySwanAnalyzer\n >>> analyzer = GraySwanAnalyzer()\n >>> risk = analyzer.security_risk(action_event)" + }, + "GraySwanAnalyzer-Output": { + "properties": { + "history_limit": { + "type": "integer", + "title": "History Limit", + "description": "Number of recent events to include as context", + "default": 20 + }, + "max_message_chars": { + "type": "integer", + "title": "Max Message Chars", + "description": "Max characters for conversation processing", + "default": 30000 + }, + "timeout": { + "type": "number", + "title": "Timeout", + "description": "Request timeout in seconds", + "default": 30.0 + }, + "low_threshold": { + "type": "number", + "title": "Low Threshold", + "description": "Risk threshold for LOW classification (score <= threshold)", + "default": 0.3 + }, + "medium_threshold": { + "type": "number", + "title": "Medium Threshold", + "description": "Risk threshold for MEDIUM classification (score <= threshold)", + "default": 0.7 + }, + "api_url": { + "type": "string", + "title": "Api Url", + "description": "GraySwan Cygnal API endpoint", + "default": "https://api.grayswan.ai/cygnal/monitor" + }, + "api_key": { + "anyOf": [ + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Api Key", + "description": "GraySwan API key (via GRAYSWAN_API_KEY env var)" + }, + "policy_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Policy Id", + "description": "GraySwan policy ID (via GRAYSWAN_POLICY_ID env var)" + }, + "kind": { + "type": "string", + "const": "GraySwanAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "GraySwanAnalyzer", + "description": "Security analyzer using GraySwan's Cygnal API for AI safety monitoring.\n\nThis analyzer sends conversation history and pending actions to the GraySwan\nCygnal API for security analysis. The API returns a violation score which is\nmapped to SecurityRisk levels.\n\nEnvironment Variables:\n GRAYSWAN_API_KEY: Required API key for GraySwan authentication\n GRAYSWAN_POLICY_ID: Optional policy ID for custom GraySwan policy\n\nExample:\n >>> from openhands.sdk.security.grayswan import GraySwanAnalyzer\n >>> analyzer = GraySwanAnalyzer()\n >>> risk = analyzer.security_risk(action_event)" + }, + "GrepAction": { + "properties": { + "pattern": { + "type": "string", + "title": "Pattern", + "description": "The regex pattern to search for in file contents" + }, + "path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Path", + "description": "The directory (absolute path) to search in. Defaults to the current working directory." + }, + "include": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Include", + "description": "Optional file pattern to filter which files to search (e.g., \"*.js\", \"*.{ts,tsx}\")" + }, + "kind": { + "type": "string", + "const": "GrepAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["pattern", "kind"], + "title": "GrepAction", + "description": "Schema for grep content search operations." + }, + "GrepActionWithRisk": { + "properties": { + "pattern": { + "type": "string", + "title": "Pattern", + "description": "The regex pattern to search for in file contents" + }, + "path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Path", + "description": "The directory (absolute path) to search in. Defaults to the current working directory." + }, + "include": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Include", + "description": "Optional file pattern to filter which files to search (e.g., \"*.js\", \"*.{ts,tsx}\")" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "GrepActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["pattern", "kind"], + "title": "GrepActionWithRisk" + }, + "GrepObservation": { + "properties": { + "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 + }, + "matches": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Matches", + "description": "List of file paths containing the pattern" + }, + "pattern": { + "type": "string", + "title": "Pattern", + "description": "The regex pattern that was used" + }, + "search_path": { + "type": "string", + "title": "Search Path", + "description": "The directory that was searched" + }, + "include_pattern": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Include Pattern", + "description": "The file pattern filter that was used" + }, + "truncated": { + "type": "boolean", + "title": "Truncated", + "description": "Whether results were truncated to 100 files", + "default": false + }, + "kind": { + "type": "string", + "const": "GrepObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["matches", "pattern", "search_path", "kind"], + "title": "GrepObservation", + "description": "Observation from grep content search operations." + }, + "GrepTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "GrepTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "GrepTool", + "description": "A ToolDefinition subclass that automatically initializes a GrepExecutor." + }, + "HTTPValidationError": { + "properties": { + "detail": { + "items": { + "$ref": "#/components/schemas/ValidationError" + }, + "type": "array", + "title": "Detail" + } + }, + "type": "object", + "title": "HTTPValidationError" + }, + "HealthStatus": { + "properties": { + "status": { + "type": "string", + "title": "Status" + } + }, + "type": "object", + "required": ["status"], + "title": "HealthStatus" + }, + "HomeResponse": { + "properties": { + "home": { + "type": "string", + "title": "Home" + }, + "favorites": { + "items": { + "$ref": "#/components/schemas/FileBrowserEntry" + }, + "type": "array", + "title": "Favorites", + "default": [] + }, + "locations": { + "items": { + "$ref": "#/components/schemas/FileBrowserEntry" + }, + "type": "array", + "title": "Locations", + "default": [] + } + }, + "type": "object", + "required": ["home"], + "title": "HomeResponse" + }, + "HookConfig-Input": { + "properties": { + "pre_tool_use": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Input" + }, + "type": "array", + "title": "Pre Tool Use", + "description": "Hooks that run before tool execution" + }, + "post_tool_use": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Input" + }, + "type": "array", + "title": "Post Tool Use", + "description": "Hooks that run after tool execution" + }, + "user_prompt_submit": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Input" + }, + "type": "array", + "title": "User Prompt Submit", + "description": "Hooks that run when user submits a prompt" + }, + "session_start": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Input" + }, + "type": "array", + "title": "Session Start", + "description": "Hooks that run when a session starts" + }, + "session_end": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Input" + }, + "type": "array", + "title": "Session End", + "description": "Hooks that run when a session ends" + }, + "stop": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Input" + }, + "type": "array", + "title": "Stop", + "description": "Hooks that run when the agent attempts to stop" + } + }, + "additionalProperties": false, + "type": "object", + "title": "HookConfig", + "description": "Configuration for all hooks.\n\nHooks can be configured either by loading from `.openhands/hooks.json` or\nby directly instantiating with typed fields:\n\n # Direct instantiation with typed fields (recommended):\n config = HookConfig(\n pre_tool_use=[\n HookMatcher(\n matcher=\"terminal\",\n hooks=[HookDefinition(command=\"block_dangerous.sh\")]\n )\n ]\n )\n\n # Load from JSON file:\n config = HookConfig.load(\".openhands/hooks.json\")" + }, + "HookConfig-Output": { + "properties": { + "pre_tool_use": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Output" + }, + "type": "array", + "title": "Pre Tool Use", + "description": "Hooks that run before tool execution" + }, + "post_tool_use": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Output" + }, + "type": "array", + "title": "Post Tool Use", + "description": "Hooks that run after tool execution" + }, + "user_prompt_submit": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Output" + }, + "type": "array", + "title": "User Prompt Submit", + "description": "Hooks that run when user submits a prompt" + }, + "session_start": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Output" + }, + "type": "array", + "title": "Session Start", + "description": "Hooks that run when a session starts" + }, + "session_end": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Output" + }, + "type": "array", + "title": "Session End", + "description": "Hooks that run when a session ends" + }, + "stop": { + "items": { + "$ref": "#/components/schemas/HookMatcher-Output" + }, + "type": "array", + "title": "Stop", + "description": "Hooks that run when the agent attempts to stop" + } + }, + "additionalProperties": false, + "type": "object", + "title": "HookConfig", + "description": "Configuration for all hooks.\n\nHooks can be configured either by loading from `.openhands/hooks.json` or\nby directly instantiating with typed fields:\n\n # Direct instantiation with typed fields (recommended):\n config = HookConfig(\n pre_tool_use=[\n HookMatcher(\n matcher=\"terminal\",\n hooks=[HookDefinition(command=\"block_dangerous.sh\")]\n )\n ]\n )\n\n # Load from JSON file:\n config = HookConfig.load(\".openhands/hooks.json\")" + }, + "HookDefinition": { + "properties": { + "type": { + "$ref": "#/components/schemas/HookType", + "default": "command" + }, + "command": { + "type": "string", + "title": "Command" + }, + "prompt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Prompt" + }, + "timeout": { + "type": "integer", + "title": "Timeout", + "default": 60 + }, + "async": { + "type": "boolean", + "title": "Async", + "default": false + } + }, + "type": "object", + "required": ["command"], + "title": "HookDefinition", + "description": "A single hook definition." + }, + "HookExecutionEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "description": "Source is always 'hook' for hook execution events", + "default": "hook" + }, + "hook_event_type": { + "type": "string", + "enum": [ + "PreToolUse", + "PostToolUse", + "UserPromptSubmit", + "SessionStart", + "SessionEnd", + "Stop" + ], + "title": "Hook Event Type", + "description": "The type of hook event that triggered this execution" + }, + "hook_command": { + "type": "string", + "title": "Hook Command", + "description": "The hook command that was executed" + }, + "tool_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Tool Name", + "description": "Tool name for PreToolUse/PostToolUse hooks" + }, + "success": { + "type": "boolean", + "title": "Success", + "description": "Whether the hook executed successfully" + }, + "blocked": { + "type": "boolean", + "title": "Blocked", + "description": "Whether the hook blocked the operation (exit code 2 or deny)", + "default": false + }, + "exit_code": { + "type": "integer", + "title": "Exit Code", + "description": "Exit code from the hook command" + }, + "stdout": { + "type": "string", + "title": "Stdout", + "description": "Standard output from the hook", + "default": "" + }, + "stderr": { + "type": "string", + "title": "Stderr", + "description": "Standard error from the hook", + "default": "" + }, + "reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Reason", + "description": "Reason provided by hook (for blocking)" + }, + "additional_context": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Additional Context", + "description": "Additional context injected by hook (e.g., for UserPromptSubmit)" + }, + "error": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Error", + "description": "Error message if hook execution failed" + }, + "action_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Action Id", + "description": "ID of the action this hook is associated with (PreToolUse/PostToolUse)" + }, + "message_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Message Id", + "description": "ID of the message this hook is associated with (UserPromptSubmit)" + }, + "hook_input": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Hook Input", + "description": "The input data that was passed to the hook" + }, + "kind": { + "type": "string", + "const": "HookExecutionEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["hook_event_type", "hook_command", "success", "exit_code", "kind"], + "title": "HookExecutionEvent", + "description": "Event emitted when a hook is executed.\n\nThis event provides observability into hook execution, including:\n- Which hook type was triggered\n- The command that was run\n- The result (success/blocked/error)\n- Any output from the hook\n\nThis allows clients to track hook execution via the event stream." + }, + "HookMatcher-Input": { + "properties": { + "matcher": { + "type": "string", + "title": "Matcher", + "default": "*" + }, + "hooks": { + "items": { + "$ref": "#/components/schemas/HookDefinition" + }, + "type": "array", + "title": "Hooks" + } + }, + "type": "object", + "title": "HookMatcher", + "description": "Matches events to hooks based on patterns.\n\nSupports exact match, wildcard (*), and regex (auto-detected or /pattern/)." + }, + "HookMatcher-Output": { + "properties": { + "matcher": { + "type": "string", + "title": "Matcher", + "default": "*" + }, + "hooks": { + "items": { + "$ref": "#/components/schemas/HookDefinition" + }, + "type": "array", + "title": "Hooks" + } + }, + "type": "object", + "title": "HookMatcher", + "description": "Matches events to hooks based on patterns.\n\nSupports exact match, wildcard (*), and regex (auto-detected or /pattern/)." + }, + "HookType": { + "type": "string", + "enum": ["command", "prompt"], + "title": "HookType", + "description": "Types of hooks that can be executed." + }, + "HooksRequest": { + "properties": { + "project_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Project Dir", + "description": "Workspace directory path for project hooks" + } + }, + "type": "object", + "title": "HooksRequest", + "description": "Request body for loading hooks." + }, + "HooksResponse": { + "properties": { + "hook_config": { + "anyOf": [ + { + "$ref": "#/components/schemas/HookConfig-Output" + }, + { + "type": "null" + } + ], + "description": "Hook configuration loaded from the workspace, or None if not found" + } + }, + "type": "object", + "title": "HooksResponse", + "description": "Response containing hooks configuration." + }, + "Icon": { + "properties": { + "src": { + "type": "string", + "title": "Src" + }, + "mimeType": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Mimetype" + }, + "sizes": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Sizes" + } + }, + "additionalProperties": true, + "type": "object", + "required": ["src"], + "title": "Icon", + "description": "An icon for display in user interfaces." + }, + "ImageContent": { + "properties": { + "cache_prompt": { + "type": "boolean", + "title": "Cache Prompt", + "default": false + }, + "type": { + "type": "string", + "const": "image", + "title": "Type", + "default": "image" + }, + "image_urls": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Image Urls" + } + }, + "type": "object", + "required": ["image_urls"], + "title": "ImageContent" + }, + "InputMetadata": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "Name of the input parameter" + }, + "description": { + "type": "string", + "title": "Description", + "description": "Description of the input parameter" + } + }, + "type": "object", + "required": ["name", "description"], + "title": "InputMetadata", + "description": "Metadata for task skill inputs." + }, + "InvokeSkillAction": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "Name of the loaded skill to invoke." + }, + "kind": { + "type": "string", + "const": "InvokeSkillAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["name", "kind"], + "title": "InvokeSkillAction" + }, + "InvokeSkillActionWithRisk": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "Name of the loaded skill to invoke." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "InvokeSkillActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["name", "kind"], + "title": "InvokeSkillActionWithRisk" + }, + "InvokeSkillObservation": { + "properties": { + "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 + }, + "skill_name": { + "type": "string", + "title": "Skill Name", + "description": "Name of the skill this observation corresponds to." + }, + "kind": { + "type": "string", + "const": "InvokeSkillObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["skill_name", "kind"], + "title": "InvokeSkillObservation" + }, + "InvokeSkillTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "InvokeSkillTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "InvokeSkillTool", + "description": "Built-in tool for explicit invocation of progressive-disclosure skills." + }, + "IterativeRefinementConfig": { + "properties": { + "success_threshold": { + "type": "number", + "maximum": 1.0, + "minimum": 0.0, + "title": "Success Threshold", + "description": "Score threshold (0-1) to consider task successful.", + "default": 0.6 + }, + "max_iterations": { + "type": "integer", + "minimum": 1.0, + "title": "Max Iterations", + "description": "Maximum number of iterations before giving up.", + "default": 3 + } + }, + "type": "object", + "title": "IterativeRefinementConfig", + "description": "Configuration for iterative refinement based on critic feedback.\n\nWhen attached to a CriticBase, the Conversation.run() method will\nautomatically retry the task if the critic score is below the threshold.\n\nExample:\n critic = APIBasedCritic(\n server_url=\"...\",\n api_key=\"...\",\n model_name=\"critic\",\n iterative_refinement=IterativeRefinementConfig(\n success_threshold=0.7,\n max_iterations=3,\n ),\n )\n agent = Agent(llm=llm, tools=tools, critic=critic)\n conversation = Conversation(agent=agent, workspace=workspace)\n conversation.send_message(\"Create a calculator module...\")\n conversation.run() # Will automatically retry if critic score < 0.7" + }, + "KeywordTrigger": { + "properties": { + "type": { + "type": "string", + "const": "keyword", + "title": "Type", + "default": "keyword" + }, + "keywords": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Keywords" + } + }, + "type": "object", + "required": ["keywords"], + "title": "KeywordTrigger", + "description": "Trigger for keyword-based skills.\n\nThese skills are activated when specific keywords appear in the user's query." + }, + "LLM-Input": { + "properties": { + "model": { + "type": "string", + "title": "Model", + "description": "Model name.", + "default": "claude-sonnet-4-20250514", + "openhands_settings": { + "depends_on": [], + "prominence": "critical" + } + }, + "api_key": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Api Key", + "description": "API key.", + "openhands_settings": { + "depends_on": [], + "label": "API Key", + "prominence": "critical" + } + }, + "base_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Base Url", + "description": "Custom base URL.", + "openhands_settings": { + "depends_on": [], + "prominence": "major" + } + }, + "api_version": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Api Version", + "description": "API version (e.g., Azure)." + }, + "aws_access_key_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Aws Access Key Id" + }, + "aws_secret_access_key": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Aws Secret Access Key" + }, + "aws_session_token": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Aws Session Token" + }, + "aws_region_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Region Name" + }, + "aws_profile_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Profile Name" + }, + "aws_role_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Role Name" + }, + "aws_session_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Session Name" + }, + "aws_bedrock_runtime_endpoint": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Bedrock Runtime Endpoint" + }, + "openrouter_site_url": { + "type": "string", + "title": "Openrouter Site Url", + "default": "https://docs.all-hands.dev/" + }, + "openrouter_app_name": { + "type": "string", + "title": "Openrouter App Name", + "default": "OpenHands" + }, + "num_retries": { + "type": "integer", + "minimum": 0.0, + "title": "Num Retries", + "default": 5 + }, + "retry_multiplier": { + "type": "number", + "minimum": 0.0, + "title": "Retry Multiplier", + "default": 8.0 + }, + "retry_min_wait": { + "type": "integer", + "minimum": 0.0, + "title": "Retry Min Wait", + "default": 8 + }, + "retry_max_wait": { + "type": "integer", + "minimum": 0.0, + "title": "Retry Max Wait", + "default": 64 + }, + "timeout": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Timeout", + "description": "HTTP timeout in seconds. Default is 300s (5 minutes). Set to None to disable timeout (not recommended for production).", + "default": 300 + }, + "max_message_chars": { + "type": "integer", + "minimum": 1.0, + "title": "Max Message Chars", + "description": "Approx max chars in each event/content sent to the LLM.", + "default": 30000 + }, + "temperature": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Temperature", + "description": "Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses." + }, + "top_p": { + "anyOf": [ + { + "type": "number", + "maximum": 1.0, + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Top P", + "description": "Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs." + }, + "top_k": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Top K" + }, + "max_input_tokens": { + "anyOf": [ + { + "type": "integer", + "minimum": 1.0 + }, + { + "type": "null" + } + ], + "title": "Max Input Tokens", + "description": "The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4)." + }, + "max_output_tokens": { + "anyOf": [ + { + "type": "integer", + "minimum": 1.0 + }, + { + "type": "null" + } + ], + "title": "Max Output Tokens", + "description": "The maximum number of output tokens. This is sent to the LLM." + }, + "model_canonical_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Model Canonical Name", + "description": "Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups." + }, + "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": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Input Cost Per Token", + "description": "The cost per input token. This will available in logs for user." + }, + "output_cost_per_token": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Output Cost Per Token", + "description": "The cost per output token. This will available in logs for user." + }, + "ollama_base_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Ollama Base Url" + }, + "stream": { + "type": "boolean", + "title": "Stream", + "description": "Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens.", + "default": false + }, + "drop_params": { + "type": "boolean", + "title": "Drop Params", + "default": true + }, + "modify_params": { + "type": "boolean", + "title": "Modify Params", + "description": "Modify params allows litellm to do transformations like adding a default message, when a message is empty.", + "default": true + }, + "disable_vision": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Disable Vision", + "description": "If model is vision capable, this option allows to disable image processing (useful for cost reduction)." + }, + "disable_stop_word": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Disable Stop Word", + "description": "Disable using of stop word.", + "default": false + }, + "caching_prompt": { + "type": "boolean", + "title": "Caching Prompt", + "description": "Enable caching of prompts.", + "default": true + }, + "log_completions": { + "type": "boolean", + "title": "Log Completions", + "description": "Enable logging of completions.", + "default": false + }, + "log_completions_folder": { + "type": "string", + "title": "Log Completions Folder", + "description": "The folder to log LLM completions to. Required if log_completions is True.", + "default": "logs/completions" + }, + "custom_tokenizer": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Custom Tokenizer", + "description": "A custom tokenizer to use for token counting." + }, + "native_tool_calling": { + "type": "boolean", + "title": "Native Tool Calling", + "description": "Whether to use native tool calling.", + "default": true + }, + "force_string_serializer": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Force String Serializer", + "description": "Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq." + }, + "reasoning_effort": { + "anyOf": [ + { + "type": "string", + "enum": ["low", "medium", "high", "xhigh", "none"] + }, + { + "type": "null" + } + ], + "title": "Reasoning Effort", + "description": "The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', 'xhigh', 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", + "title": "Enable Encrypted Reasoning", + "description": "If True, ask for ['reasoning.encrypted_content'] in Responses API include.", + "default": true + }, + "prompt_cache_retention": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Prompt Cache Retention", + "description": "Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others.", + "default": "24h" + }, + "extended_thinking_budget": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Extended Thinking Budget", + "description": "The budget tokens for extended thinking, supported by Anthropic models.", + "default": 200000 + }, + "seed": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Seed", + "description": "The seed to use for random number generation." + }, + "usage_id": { + "type": "string", + "title": "Usage Id", + "description": "Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.", + "default": "default" + }, + "litellm_extra_body": { + "additionalProperties": true, + "type": "object", + "title": "Litellm Extra Body", + "description": "Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True}" + }, + "fallback_strategy": { + "anyOf": [ + { + "$ref": "#/components/schemas/FallbackStrategy" + }, + { + "type": "null" + } + ], + "description": "Optional fallback strategy for trying alternate LLMs on transient failure. Construct with FallbackStrategy(fallback_llms=[...]).Excluded from serialization; must be reconfigured after load." + } + }, + "type": "object", + "title": "LLM", + "description": "Language model interface for OpenHands agents.\n\nThe LLM class provides a unified interface for interacting with various\nlanguage models through the litellm library. It handles model configuration,\nAPI authentication, retry logic, and tool calling capabilities.\n\nAttributes:\n model: Model name (e.g., \"claude-sonnet-4-20250514\").\n api_key: API key for authentication.\n base_url: Custom API base URL.\n num_retries: Number of retry attempts for failed requests.\n timeout: Request timeout in seconds.\n\nExample:\n ```python\n from openhands.sdk import LLM\n from pydantic import SecretStr\n\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\n ```" + }, + "LLM-Output": { + "properties": { + "model": { + "type": "string", + "title": "Model", + "description": "Model name.", + "default": "claude-sonnet-4-20250514", + "openhands_settings": { + "depends_on": [], + "prominence": "critical" + } + }, + "api_key": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Api Key", + "description": "API key.", + "openhands_settings": { + "depends_on": [], + "label": "API Key", + "prominence": "critical" + } + }, + "base_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Base Url", + "description": "Custom base URL.", + "openhands_settings": { + "depends_on": [], + "prominence": "major" + } + }, + "api_version": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Api Version", + "description": "API version (e.g., Azure)." + }, + "aws_access_key_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Aws Access Key Id" + }, + "aws_secret_access_key": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Aws Secret Access Key" + }, + "aws_session_token": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } + ], + "title": "Aws Session Token" + }, + "aws_region_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Region Name" + }, + "aws_profile_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Profile Name" + }, + "aws_role_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Role Name" + }, + "aws_session_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Session Name" + }, + "aws_bedrock_runtime_endpoint": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Aws Bedrock Runtime Endpoint" + }, + "openrouter_site_url": { + "type": "string", + "title": "Openrouter Site Url", + "default": "https://docs.all-hands.dev/" + }, + "openrouter_app_name": { + "type": "string", + "title": "Openrouter App Name", + "default": "OpenHands" + }, + "num_retries": { + "type": "integer", + "minimum": 0.0, + "title": "Num Retries", + "default": 5 + }, + "retry_multiplier": { + "type": "number", + "minimum": 0.0, + "title": "Retry Multiplier", + "default": 8.0 + }, + "retry_min_wait": { + "type": "integer", + "minimum": 0.0, + "title": "Retry Min Wait", + "default": 8 + }, + "retry_max_wait": { + "type": "integer", + "minimum": 0.0, + "title": "Retry Max Wait", + "default": 64 + }, + "timeout": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Timeout", + "description": "HTTP timeout in seconds. Default is 300s (5 minutes). Set to None to disable timeout (not recommended for production).", + "default": 300 + }, + "max_message_chars": { + "type": "integer", + "minimum": 1.0, + "title": "Max Message Chars", + "description": "Approx max chars in each event/content sent to the LLM.", + "default": 30000 + }, + "temperature": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Temperature", + "description": "Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses." + }, + "top_p": { + "anyOf": [ + { + "type": "number", + "maximum": 1.0, + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Top P", + "description": "Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs." + }, + "top_k": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Top K" + }, + "max_input_tokens": { + "anyOf": [ + { + "type": "integer", + "minimum": 1.0 + }, + { + "type": "null" + } + ], + "title": "Max Input Tokens", + "description": "The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4)." + }, + "max_output_tokens": { + "anyOf": [ + { + "type": "integer", + "minimum": 1.0 + }, + { + "type": "null" + } + ], + "title": "Max Output Tokens", + "description": "The maximum number of output tokens. This is sent to the LLM." + }, + "model_canonical_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Model Canonical Name", + "description": "Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups." + }, + "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": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Input Cost Per Token", + "description": "The cost per input token. This will available in logs for user." + }, + "output_cost_per_token": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Output Cost Per Token", + "description": "The cost per output token. This will available in logs for user." + }, + "ollama_base_url": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Ollama Base Url" + }, + "stream": { + "type": "boolean", + "title": "Stream", + "description": "Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens.", + "default": false + }, + "drop_params": { + "type": "boolean", + "title": "Drop Params", + "default": true + }, + "modify_params": { + "type": "boolean", + "title": "Modify Params", + "description": "Modify params allows litellm to do transformations like adding a default message, when a message is empty.", + "default": true + }, + "disable_vision": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Disable Vision", + "description": "If model is vision capable, this option allows to disable image processing (useful for cost reduction)." + }, + "disable_stop_word": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Disable Stop Word", + "description": "Disable using of stop word.", + "default": false + }, + "caching_prompt": { + "type": "boolean", + "title": "Caching Prompt", + "description": "Enable caching of prompts.", + "default": true + }, + "log_completions": { + "type": "boolean", + "title": "Log Completions", + "description": "Enable logging of completions.", + "default": false + }, + "log_completions_folder": { + "type": "string", + "title": "Log Completions Folder", + "description": "The folder to log LLM completions to. Required if log_completions is True.", + "default": "logs/completions" + }, + "custom_tokenizer": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Custom Tokenizer", + "description": "A custom tokenizer to use for token counting." + }, + "native_tool_calling": { + "type": "boolean", + "title": "Native Tool Calling", + "description": "Whether to use native tool calling.", + "default": true + }, + "force_string_serializer": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Force String Serializer", + "description": "Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq." + }, + "reasoning_effort": { + "anyOf": [ + { + "type": "string", + "enum": ["low", "medium", "high", "xhigh", "none"] + }, + { + "type": "null" + } + ], + "title": "Reasoning Effort", + "description": "The effort to put into reasoning. This is a string that can be one of 'low', 'medium', 'high', 'xhigh', 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", + "title": "Enable Encrypted Reasoning", + "description": "If True, ask for ['reasoning.encrypted_content'] in Responses API include.", + "default": true + }, + "prompt_cache_retention": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Prompt Cache Retention", + "description": "Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others.", + "default": "24h" + }, + "extended_thinking_budget": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Extended Thinking Budget", + "description": "The budget tokens for extended thinking, supported by Anthropic models.", + "default": 200000 + }, + "seed": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Seed", + "description": "The seed to use for random number generation." + }, + "usage_id": { + "type": "string", + "title": "Usage Id", + "description": "Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.", + "default": "default" + }, + "litellm_extra_body": { + "additionalProperties": true, + "type": "object", + "title": "Litellm Extra Body", + "description": "Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True}" + } + }, + "type": "object", + "title": "LLM", + "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, retry logic, and tool calling capabilities.\n\nAttributes:\n model: Model name (e.g., \"claude-sonnet-4-20250514\").\n api_key: API key for authentication.\n base_url: Custom API base URL.\n num_retries: Number of retry attempts for failed requests.\n timeout: Request timeout in seconds.\n\nExample:\n ```python\n from openhands.sdk import LLM\n from pydantic import SecretStr\n\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\n ```" + }, + "LLMCompletionLogEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "environment" + }, + "filename": { + "type": "string", + "title": "Filename", + "description": "The intended filename for this log (relative to log directory)" + }, + "log_data": { + "type": "string", + "title": "Log Data", + "description": "The JSON-encoded log data to be written to the file" + }, + "model_name": { + "type": "string", + "title": "Model Name", + "description": "The model name for context", + "default": "unknown" + }, + "usage_id": { + "type": "string", + "title": "Usage Id", + "description": "The LLM usage_id that produced this log", + "default": "default" + }, + "kind": { + "type": "string", + "const": "LLMCompletionLogEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["filename", "log_data", "kind"], + "title": "LLMCompletionLogEvent", + "description": "Event containing LLM completion log data.\n\nWhen an LLM is configured with log_completions=True in a remote conversation,\nthis event streams the completion log data back to the client through WebSocket\ninstead of writing it to a file inside the Docker container." + }, + "LLMSecurityAnalyzer-Input": { + "properties": { + "kind": { + "type": "string", + "const": "LLMSecurityAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "title": "LLMSecurityAnalyzer", + "description": "LLM-based security analyzer.\n\nThis analyzer respects the security_risk attribute that can be set by the LLM\nwhen generating actions, similar to OpenHands' LLMRiskAnalyzer.\n\nIt provides a lightweight security analysis approach that leverages the LLM's\nunderstanding of action context and potential risks." + }, + "LLMSecurityAnalyzer-Output": { + "properties": { + "kind": { + "type": "string", + "const": "LLMSecurityAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "LLMSecurityAnalyzer", + "description": "LLM-based security analyzer.\n\nThis analyzer respects the security_risk attribute that can be set by the LLM\nwhen generating actions, similar to OpenHands' LLMRiskAnalyzer.\n\nIt provides a lightweight security analysis approach that leverages the LLM's\nunderstanding of action context and potential risks." + }, + "LLMSummarizingCondenser-Input": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Input" + }, + "max_size": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Max Size", + "default": 240 + }, + "max_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Max Tokens" + }, + "keep_first": { + "type": "integer", + "minimum": 0.0, + "title": "Keep First", + "default": 2 + }, + "minimum_progress": { + "type": "number", + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Minimum Progress", + "default": 0.1 + }, + "hard_context_reset_max_retries": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Hard Context Reset Max Retries", + "default": 5 + }, + "hard_context_reset_context_scaling": { + "type": "number", + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Hard Context Reset Context Scaling", + "default": 0.8 + }, + "kind": { + "type": "string", + "const": "LLMSummarizingCondenser", + "title": "Kind" + } + }, + "type": "object", + "required": ["llm"], + "title": "LLMSummarizingCondenser", + "description": "LLM-based condenser that summarizes forgotten events.\n\nUses an independent LLM (stored in the `llm` attribute) for generating summaries\nof forgotten events. The optional `agent_llm` parameter passed to condense() is\nthe LLM used by the agent for token counting purposes, and you should not assume\nit is the same as the one defined in this condenser." + }, + "LLMSummarizingCondenser-Output": { + "properties": { + "llm": { + "$ref": "#/components/schemas/LLM-Output" + }, + "max_size": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Max Size", + "default": 240 + }, + "max_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Max Tokens" + }, + "keep_first": { + "type": "integer", + "minimum": 0.0, + "title": "Keep First", + "default": 2 + }, + "minimum_progress": { + "type": "number", + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Minimum Progress", + "default": 0.1 + }, + "hard_context_reset_max_retries": { + "type": "integer", + "exclusiveMinimum": 0.0, + "title": "Hard Context Reset Max Retries", + "default": 5 + }, + "hard_context_reset_context_scaling": { + "type": "number", + "exclusiveMaximum": 1.0, + "exclusiveMinimum": 0.0, + "title": "Hard Context Reset Context Scaling", + "default": 0.8 + }, + "kind": { + "type": "string", + "const": "LLMSummarizingCondenser", + "title": "Kind" + } + }, + "type": "object", + "required": ["llm", "kind"], + "title": "LLMSummarizingCondenser", + "description": "LLM-based condenser that summarizes forgotten events.\n\nUses an independent LLM (stored in the `llm` attribute) for generating summaries\nof forgotten events. The optional `agent_llm` parameter passed to condense() is\nthe LLM used by the agent for token counting purposes, and you should not assume\nit is the same as the one defined in this condenser." + }, + "ListDirectoryAction": { + "properties": { + "dir_path": { + "type": "string", + "title": "Dir Path", + "description": "The path to the directory to list. Defaults to current directory.", + "default": "." + }, + "recursive": { + "type": "boolean", + "title": "Recursive", + "description": "Whether to list subdirectories recursively (up to 2 levels).", + "default": false + }, + "kind": { + "type": "string", + "const": "ListDirectoryAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "ListDirectoryAction", + "description": "Schema for list directory operation." + }, + "ListDirectoryActionWithRisk": { + "properties": { + "dir_path": { + "type": "string", + "title": "Dir Path", + "description": "The path to the directory to list. Defaults to current directory.", + "default": "." + }, + "recursive": { + "type": "boolean", + "title": "Recursive", + "description": "Whether to list subdirectories recursively (up to 2 levels).", + "default": false + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "ListDirectoryActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "ListDirectoryActionWithRisk" + }, + "ListDirectoryObservation": { + "properties": { + "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 + }, + "dir_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Dir Path", + "description": "The directory path that was listed." + }, + "entries": { + "items": { + "$ref": "#/components/schemas/FileEntry" + }, + "type": "array", + "title": "Entries", + "description": "List of files and directories found." + }, + "total_count": { + "type": "integer", + "title": "Total Count", + "description": "Total number of entries found.", + "default": 0 + }, + "is_truncated": { + "type": "boolean", + "title": "Is Truncated", + "description": "Whether the listing was truncated due to too many entries.", + "default": false + }, + "kind": { + "type": "string", + "const": "ListDirectoryObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "ListDirectoryObservation", + "description": "Observation from listing a directory." + }, + "ListDirectoryTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "ListDirectoryTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "ListDirectoryTool", + "description": "Tool for listing directory contents with metadata." + }, + "LocalWorkspace-Input": { + "properties": { + "working_dir": { + "type": "string", + "title": "Working Dir", + "description": "The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings." + }, + "kind": { + "type": "string", + "const": "LocalWorkspace", + "title": "Kind" + } + }, + "type": "object", + "required": ["working_dir"], + "title": "LocalWorkspace", + "description": "Local workspace implementation that operates on the host filesystem.\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\")" + }, + "LocalWorkspace-Output": { + "properties": { + "working_dir": { + "type": "string", + "title": "Working Dir", + "description": "The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings." + }, + "kind": { + "type": "string", + "const": "LocalWorkspace", + "title": "Kind" + } + }, + "type": "object", + "required": ["working_dir", "kind"], + "title": "LocalWorkspace", + "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-Input": { + "properties": { + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description", + "description": "Optional description for this secret" + }, + "url": { + "type": "string", + "title": "Url" + }, + "headers": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Headers" + }, + "kind": { + "type": "string", + "const": "LookupSecret", + "title": "Kind" + } + }, + "type": "object", + "required": ["url"], + "title": "LookupSecret", + "description": "A secret looked up from some external url" + }, + "LookupSecret-Output": { + "properties": { + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description", + "description": "Optional description for this secret" + }, + "url": { + "type": "string", + "title": "Url" + }, + "headers": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Headers" + }, + "kind": { + "type": "string", + "const": "LookupSecret", + "title": "Kind" + } + }, + "type": "object", + "required": ["url", "kind"], + "title": "LookupSecret", + "description": "A secret looked up from some external url" + }, + "MCPToolAction": { + "properties": { + "data": { + "additionalProperties": true, + "type": "object", + "title": "Data", + "description": "Dynamic data fields from the tool call" + }, + "kind": { + "type": "string", + "const": "MCPToolAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "MCPToolAction", + "description": "Schema for MCP input action.\n\nIt is just a thin wrapper around raw JSON and does\nnot do any validation.\n\nValidation will be performed by MCPTool.__call__\nby constructing dynamically created Pydantic model\nfrom the MCP tool input schema." + }, + "MCPToolActionWithRisk": { + "properties": { + "data": { + "additionalProperties": true, + "type": "object", + "title": "Data", + "description": "Dynamic data fields from the tool call" + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "MCPToolActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "MCPToolActionWithRisk" + }, + "MCPToolDefinition": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "mcp_tool": { + "$ref": "#/components/schemas/mcp__types__Tool", + "description": "The MCP tool definition." + }, + "kind": { + "type": "string", + "const": "MCPToolDefinition", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "mcp_tool", "kind", "title"], + "title": "MCPToolDefinition", + "description": "MCP Tool that wraps an MCP client and provides tool functionality." + }, + "MCPToolObservation": { + "properties": { + "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 + }, + "tool_name": { + "type": "string", + "title": "Tool Name", + "description": "Name of the tool that was called" + }, + "kind": { + "type": "string", + "const": "MCPToolObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tool_name", "kind"], + "title": "MCPToolObservation", + "description": "Observation from MCP tool execution." + }, + "Message": { + "properties": { + "role": { + "type": "string", + "enum": ["user", "system", "assistant", "tool"], + "title": "Role" + }, + "content": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", + "title": "Content" + }, + "tool_calls": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/MessageToolCall" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tool Calls" + }, + "tool_call_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Tool Call Id" + }, + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name" + }, + "reasoning_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Reasoning Content", + "description": "Intermediate reasoning/thinking content from reasoning models" + }, + "thinking_blocks": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/ThinkingBlock" + }, + { + "$ref": "#/components/schemas/RedactedThinkingBlock" + } + ] + }, + "type": "array", + "title": "Thinking Blocks", + "description": "Raw Anthropic thinking blocks for extended thinking feature" + }, + "responses_reasoning_item": { + "anyOf": [ + { + "$ref": "#/components/schemas/ReasoningItemModel" + }, + { + "type": "null" + } + ], + "description": "OpenAI Responses reasoning item from model output" + } + }, + "type": "object", + "required": ["role"], + "title": "Message" + }, + "MessageEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source" + }, + "llm_message": { + "$ref": "#/components/schemas/Message", + "description": "The exact LLM message for this message event" + }, + "llm_response_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Llm Response Id", + "description": "Completion or Response ID of the LLM response that generated this eventIf the source != 'agent', this field is None" + }, + "activated_skills": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Activated Skills", + "description": "List of activated skill name" + }, + "extended_content": { + "items": { + "$ref": "#/components/schemas/TextContent" + }, + "type": "array", + "title": "Extended Content", + "description": "List of content added by agent context" + }, + "sender": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Sender", + "description": "Optional identifier of the sender. Can be used to track message origin in multi-agent scenarios." + }, + "critic_result": { + "anyOf": [ + { + "$ref": "#/components/schemas/CriticResult" + }, + { + "type": "null" + } + ], + "description": "Optional critic evaluation of this message and preceding history." + }, + "kind": { + "type": "string", + "const": "MessageEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["source", "llm_message", "kind"], + "title": "MessageEvent", + "description": "Message from either agent or user.\n\nThis is originally the \"MessageAction\", but it suppose not to be tool call." + }, + "MessageToolCall": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Canonical tool call id" + }, + "responses_item_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Responses Item Id", + "description": "Original Responses function_call.id, echoed verbatim on replay" + }, + "name": { + "type": "string", + "title": "Name", + "description": "Tool/function name" + }, + "arguments": { + "type": "string", + "title": "Arguments", + "description": "JSON string of arguments" + }, + "origin": { + "type": "string", + "enum": ["completion", "responses"], + "title": "Origin", + "description": "Originating API family" + } + }, + "type": "object", + "required": ["id", "name", "arguments", "origin"], + "title": "MessageToolCall", + "description": "Transport-agnostic tool call representation.\n\nOne canonical id is used for linking across actions/observations and\nfor Responses function_call_output call_id." + }, + "Metrics": { + "properties": { + "model_name": { + "type": "string", + "title": "Model Name", + "description": "Name of the model", + "default": "default" + }, + "accumulated_cost": { + "type": "number", + "minimum": 0.0, + "title": "Accumulated Cost", + "description": "Total accumulated cost, must be non-negative", + "default": 0.0 + }, + "max_budget_per_task": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Max Budget Per Task", + "description": "Maximum budget per task" + }, + "accumulated_token_usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/TokenUsage" + }, + { + "type": "null" + } + ], + "description": "Accumulated token usage across all calls" + }, + "costs": { + "items": { + "$ref": "#/components/schemas/Cost" + }, + "type": "array", + "title": "Costs", + "description": "List of individual costs" + }, + "response_latencies": { + "items": { + "$ref": "#/components/schemas/ResponseLatency" + }, + "type": "array", + "title": "Response Latencies", + "description": "List of response latencies" + }, + "token_usages": { + "items": { + "$ref": "#/components/schemas/TokenUsage" + }, + "type": "array", + "title": "Token Usages", + "description": "List of token usage records" + } + }, + "type": "object", + "title": "Metrics", + "description": "Metrics class can record various metrics during running and evaluation.\nWe track:\n - accumulated_cost and costs\n - max_budget_per_task (budget limit)\n - A list of ResponseLatency\n - A list of TokenUsage (one per call)." + }, + "MetricsSnapshot": { + "properties": { + "model_name": { + "type": "string", + "title": "Model Name", + "description": "Name of the model", + "default": "default" + }, + "accumulated_cost": { + "type": "number", + "minimum": 0.0, + "title": "Accumulated Cost", + "description": "Total accumulated cost, must be non-negative", + "default": 0.0 + }, + "max_budget_per_task": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Max Budget Per Task", + "description": "Maximum budget per task" + }, + "accumulated_token_usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/TokenUsage" + }, + { + "type": "null" + } + ], + "description": "Accumulated token usage across all calls" + } + }, + "type": "object", + "title": "MetricsSnapshot", + "description": "A snapshot of metrics at a point in time.\n\nDoes not include lists of individual costs, latencies, or token usages." + }, + "ModelsResponse": { + "properties": { + "models": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Models" + } + }, + "type": "object", + "required": ["models"], + "title": "ModelsResponse", + "description": "Response containing the list of available LLM models." + }, + "NeverConfirm-Input": { + "properties": { + "kind": { + "type": "string", + "const": "NeverConfirm", + "title": "Kind" + } + }, + "type": "object", + "title": "NeverConfirm" + }, + "NeverConfirm-Output": { + "properties": { + "kind": { + "type": "string", + "const": "NeverConfirm", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "NeverConfirm" + }, + "NoOpCondenser-Input": { + "properties": { + "kind": { + "type": "string", + "const": "NoOpCondenser", + "title": "Kind" + } + }, + "type": "object", + "title": "NoOpCondenser", + "description": "Simple condenser that returns a view un-manipulated.\n\nPrimarily intended for testing purposes." + }, + "NoOpCondenser-Output": { + "properties": { + "kind": { + "type": "string", + "const": "NoOpCondenser", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "NoOpCondenser", + "description": "Simple condenser that returns a view un-manipulated.\n\nPrimarily intended for testing purposes." + }, + "Observation": { + "oneOf": [ + { + "$ref": "#/components/schemas/MCPToolObservation" + }, + { + "$ref": "#/components/schemas/FinishObservation" + }, + { + "$ref": "#/components/schemas/InvokeSkillObservation" + }, + { + "$ref": "#/components/schemas/SwitchLLMObservation" + }, + { + "$ref": "#/components/schemas/ThinkObservation" + }, + { + "$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" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__mcp__definition__MCPToolObservation-Output__1": "#/components/schemas/MCPToolObservation", + "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__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" + } + } + }, + "ObservationEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, "source": { "type": "string", - "enum": [ - "agent", - "user", - "environment" + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "environment" + }, + "tool_name": { + "type": "string", + "title": "Tool Name", + "description": "The tool name that this observation is responding to" + }, + "tool_call_id": { + "type": "string", + "title": "Tool Call Id", + "description": "The tool call id that this observation is responding to" + }, + "observation": { + "$ref": "#/components/schemas/Observation", + "description": "The observation (tool call) sent to LLM" + }, + "action_id": { + "type": "string", + "title": "Action Id", + "description": "The action id that this observation is responding to" + }, + "kind": { + "type": "string", + "const": "ObservationEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["tool_name", "tool_call_id", "observation", "action_id", "kind"], + "title": "ObservationEvent" + }, + "OrgConfig": { + "properties": { + "repository": { + "type": "string", + "title": "Repository", + "description": "Selected repository (e.g., 'owner/repo')" + }, + "provider": { + "type": "string", + "title": "Provider", + "description": "Git provider type: github, gitlab, azure, bitbucket" + }, + "org_repo_url": { + "type": "string", + "title": "Org Repo Url", + "description": "Pre-authenticated Git URL for the organization repository. Contains sensitive credentials - handle with care and avoid logging." + }, + "org_name": { + "type": "string", + "title": "Org Name", + "description": "Organization name" + } + }, + "type": "object", + "required": ["repository", "provider", "org_repo_url", "org_name"], + "title": "OrgConfig", + "description": "Configuration for loading organization-level skills." + }, + "PassCritic-Input": { + "properties": { + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" + }, + "iterative_refinement": { + "anyOf": [ + { + "$ref": "#/components/schemas/IterativeRefinementConfig" + }, + { + "type": "null" + } ], - "title": "Source", - "default": "agent" + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." }, - "thought": { - "items": { - "$ref": "#/components/schemas/TextContent" - }, - "type": "array", - "title": "Thought", - "description": "The thought process of the agent before taking this action" + "kind": { + "type": "string", + "const": "PassCritic", + "title": "Kind" + } + }, + "type": "object", + "title": "PassCritic", + "description": "Critic that always returns success.\n\nThis critic can be used when no evaluation is needed or when\nall instances should be considered successful regardless of their output." + }, + "PassCritic-Output": { + "properties": { + "mode": { + "type": "string", + "enum": ["finish_and_message", "all_actions"], + "title": "Mode", + "description": "When to run critic evaluation:\n- 'finish_and_message': Evaluate on FinishAction and agent MessageEvent (default, minimal performance impact)\n- 'all_actions': Evaluate after every agent action (WARNING: significantly slower due to API calls on each action)", + "default": "finish_and_message" }, - "reasoning_content": { + "iterative_refinement": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/IterativeRefinementConfig" }, { "type": "null" } ], - "title": "Reasoning Content", - "description": "Intermediate reasoning/thinking content from reasoning models" + "description": "Optional configuration for iterative refinement. When set, Conversation.run() will automatically retry the task if the critic score is below the success_threshold, up to max_iterations." }, - "thinking_blocks": { + "kind": { + "type": "string", + "const": "PassCritic", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "PassCritic", + "description": "Critic that always returns success.\n\nThis critic can be used when no evaluation is needed or when\nall instances should be considered successful regardless of their output." + }, + "PatternSecurityAnalyzer-Input": { + "properties": { + "high_patterns": { "items": { - "anyOf": [ + "prefixItems": [ { - "$ref": "#/components/schemas/ThinkingBlock" + "type": "string" }, { - "$ref": "#/components/schemas/RedactedThinkingBlock" + "type": "string" + }, + { + "type": "string" } - ] + ], + "type": "array", + "maxItems": 3, + "minItems": 3 }, "type": "array", - "title": "Thinking Blocks", - "description": "Anthropic thinking blocks from the LLM response" + "title": "High Patterns", + "description": "HIGH patterns scanned against executable fields only" }, - "responses_reasoning_item": { - "anyOf": [ - { - "$ref": "#/components/schemas/ReasoningItemModel" - }, - { - "type": "null" - } - ], - "description": "OpenAI Responses reasoning item from model output" + "medium_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "Medium Patterns", + "description": "MEDIUM patterns scanned against executable fields only" }, - "action": { - "anyOf": [ - { - "$ref": "#/components/schemas/Action" - }, - { - "type": "null" - } - ], - "title": "Action", - "description": "Single tool call returned by LLM (None when non-executable)" + "injection_high_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "Injection High Patterns", + "description": "HIGH patterns scanned against all fields" }, - "tool_name": { + "injection_medium_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "Injection Medium Patterns", + "description": "MEDIUM patterns scanned against all fields" + }, + "kind": { "type": "string", - "title": "Tool Name", - "description": "The name of the tool being called" + "const": "PatternSecurityAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "title": "PatternSecurityAnalyzer", + "description": "Catch dangerous agent actions through deterministic signature scanning.\n\nUse this when you want fast, local, no-network threat detection at the\naction boundary. It returns ``SecurityRisk.HIGH``, ``MEDIUM``, or ``LOW``\n-- pair it with ``ConfirmRisky`` to decide what gets confirmed.\n\nThe key design choice: shell-destructive patterns only scan what the\nagent will *execute* (tool arguments), never what it *thought about*\n(reasoning text). Injection patterns scan everything, because\n\"ignore all previous instructions\" is dangerous wherever it appears.\n\nNormalization is always on -- invisible characters and fullwidth\nsubstitutions are collapsed before matching.\n\nExample::\n\n from openhands.sdk.security import PatternSecurityAnalyzer, ConfirmRisky\n\n analyzer = PatternSecurityAnalyzer()\n policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM)" + }, + "PatternSecurityAnalyzer-Output": { + "properties": { + "high_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "High Patterns", + "description": "HIGH patterns scanned against executable fields only" }, - "tool_call_id": { + "medium_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "Medium Patterns", + "description": "MEDIUM patterns scanned against executable fields only" + }, + "injection_high_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "Injection High Patterns", + "description": "HIGH patterns scanned against all fields" + }, + "injection_medium_patterns": { + "items": { + "prefixItems": [ + { + "type": "string" + }, + { + "type": "string" + }, + { + "type": "string" + } + ], + "type": "array", + "maxItems": 3, + "minItems": 3 + }, + "type": "array", + "title": "Injection Medium Patterns", + "description": "MEDIUM patterns scanned against all fields" + }, + "kind": { "type": "string", - "title": "Tool Call Id", - "description": "The unique id returned by LLM API for this tool call" + "const": "PatternSecurityAnalyzer", + "title": "Kind" + } + }, + "type": "object", + "required": ["kind"], + "title": "PatternSecurityAnalyzer", + "description": "Catch dangerous agent actions through deterministic signature scanning.\n\nUse this when you want fast, local, no-network threat detection at the\naction boundary. It returns ``SecurityRisk.HIGH``, ``MEDIUM``, or ``LOW``\n-- pair it with ``ConfirmRisky`` to decide what gets confirmed.\n\nThe key design choice: shell-destructive patterns only scan what the\nagent will *execute* (tool arguments), never what it *thought about*\n(reasoning text). Injection patterns scan everything, because\n\"ignore all previous instructions\" is dangerous wherever it appears.\n\nNormalization is always on -- invisible characters and fullwidth\nsubstitutions are collapsed before matching.\n\nExample::\n\n from openhands.sdk.security import PatternSecurityAnalyzer, ConfirmRisky\n\n analyzer = PatternSecurityAnalyzer()\n policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM)" + }, + "PauseEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" }, - "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." + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" }, - "llm_response_id": { + "source": { "type": "string", - "title": "Llm Response Id", - "description": "Groups related actions from same LLM response. This helps in tracking and managing results of parallel function calling from the same LLM response." + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "user" }, - "security_risk": { - "$ref": "#/components/schemas/SecurityRisk", - "description": "The LLM's assessment of the safety risk of this action.", - "default": "UNKNOWN" + "kind": { + "type": "string", + "const": "PauseEvent", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "thought", - "tool_name", - "tool_call_id", - "tool_call", - "llm_response_id" - ], - "title": "ActionEvent" + "required": ["kind"], + "title": "PauseEvent", + "description": "Event indicating that the agent execution was paused by user request." + }, + "PipelineCondenser-Input": { + "properties": { + "condensers": { + "items": { + "$ref": "#/components/schemas/CondenserBase-Input" + }, + "type": "array", + "title": "Condensers" + }, + "kind": { + "type": "string", + "const": "PipelineCondenser", + "title": "Kind" + } + }, + "type": "object", + "required": ["condensers"], + "title": "PipelineCondenser", + "description": "A condenser that applies a sequence of condensers in order.\n\nAll condensers are defined primarily by their `condense` method, which takes a\n`View` and an optional `agent_llm` parameter, returning either a new `View` or a\n`Condensation` event. That means we can chain multiple condensers together by\npassing `View`s along and exiting early if any condenser returns a `Condensation`.\n\nFor example:\n\n # Use the pipeline condenser to chain multiple other condensers together\n condenser = PipelineCondenser(condensers=[\n CondenserA(...),\n CondenserB(...),\n CondenserC(...),\n ])\n\n result = condenser.condense(view, agent_llm=agent_llm)\n\n # Doing the same thing without the pipeline condenser requires more boilerplate\n # for the monadic chaining\n other_result = view\n\n if isinstance(other_result, View):\n other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm)\n\n if isinstance(other_result, View):\n other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm)\n\n if isinstance(other_result, View):\n other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm)\n\n assert result == other_result" + }, + "PipelineCondenser-Output": { + "properties": { + "condensers": { + "items": { + "$ref": "#/components/schemas/CondenserBase-Output" + }, + "type": "array", + "title": "Condensers" + }, + "kind": { + "type": "string", + "const": "PipelineCondenser", + "title": "Kind" + } + }, + "type": "object", + "required": ["condensers", "kind"], + "title": "PipelineCondenser", + "description": "A condenser that applies a sequence of condensers in order.\n\nAll condensers are defined primarily by their `condense` method, which takes a\n`View` and an optional `agent_llm` parameter, returning either a new `View` or a\n`Condensation` event. That means we can chain multiple condensers together by\npassing `View`s along and exiting early if any condenser returns a `Condensation`.\n\nFor example:\n\n # Use the pipeline condenser to chain multiple other condensers together\n condenser = PipelineCondenser(condensers=[\n CondenserA(...),\n CondenserB(...),\n CondenserC(...),\n ])\n\n result = condenser.condense(view, agent_llm=agent_llm)\n\n # Doing the same thing without the pipeline condenser requires more boilerplate\n # for the monadic chaining\n other_result = view\n\n if isinstance(other_result, View):\n other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm)\n\n if isinstance(other_result, View):\n other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm)\n\n if isinstance(other_result, View):\n other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm)\n\n assert result == other_result" }, - "Agent-Output": { + "PlanningFileEditorAction": { "properties": { - "kind": { + "command": { "type": "string", - "const": "Agent", - "title": "Kind", - "default": "Agent" + "enum": ["view", "create", "str_replace", "insert", "undo_edit"], + "title": "Command", + "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." }, - "llm": { - "$ref": "#/components/schemas/LLM", - "description": "LLM configuration for the agent.", - "examples": [ - { - "api_key": "your_api_key_here", - "base_url": "https://llm-proxy.eval.all-hands.dev", - "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" - } - ] + "path": { + "type": "string", + "title": "Path", + "description": "Absolute path to file or directory." }, - "tools": { - "items": { - "$ref": "#/components/schemas/Tool" - }, - "type": "array", - "title": "Tools", - "description": "List of tools to initialize for the agent.", - "examples": [ - { - "name": "BashTool", - "params": {} - }, + "file_text": { + "anyOf": [ { - "name": "FileEditorTool", - "params": {} + "type": "string" }, { - "name": "TaskTrackerTool", - "params": {} - } - ] - }, - "mcp_config": { - "additionalProperties": true, - "type": "object", - "title": "Mcp Config", - "description": "Optional MCP configuration dictionary to create MCP tools.", - "examples": [ - { - "mcpServers": { - "fetch": { - "args": [ - "mcp-server-fetch" - ], - "command": "uvx" - } - } + "type": "null" } - ] + ], + "title": "File Text", + "description": "Required parameter of `create` command, with the content of the file to be created." }, - "filter_tools_regex": { + "old_str": { "anyOf": [ { "type": "string" @@ -2039,118 +13785,75 @@ "type": "null" } ], - "title": "Filter Tools Regex", - "description": "Optional regex to filter the tools available to the agent by name. This is applied after any tools provided in `tools` and any MCP tools are added.", - "examples": [ - "^(?!repomix)(.*)|^repomix.*pack_codebase.*$" - ] + "title": "Old Str", + "description": "Required parameter of `str_replace` command containing the string in `path` to replace." }, - "agent_context": { + "new_str": { "anyOf": [ { - "$ref": "#/components/schemas/AgentContext-Output" + "type": "string" }, { "type": "null" } ], - "description": "Optional AgentContext to initialize the agent with specific context.", - "examples": [ - { - "skills": [ - { - "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.", - "name": "repo.md", - "type": "repo" - }, - { - "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are", - "name": "flarglebargle", - "trigger": [ - "flarglebargle" - ], - "type": "knowledge" - } - ], - "system_message_suffix": "Always finish your response with the word 'yay!'", - "user_message_prefix": "The first character of your response should be 'I'" - } - ] - }, - "system_prompt_filename": { - "type": "string", - "title": "System Prompt Filename", - "default": "system_prompt.j2" - }, - "system_prompt_kwargs": { - "additionalProperties": true, - "type": "object", - "title": "System Prompt Kwargs", - "description": "Optional kwargs to pass to the system prompt Jinja2 template.", - "examples": [ - { - "cli_mode": true - } - ] + "title": "New Str", + "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." }, - "security_analyzer": { + "insert_line": { "anyOf": [ { - "$ref": "#/components/schemas/SecurityAnalyzerBase" + "type": "integer", + "minimum": 0.0 }, { "type": "null" } ], - "description": "Optional security analyzer to evaluate action risks.", - "examples": [ - { - "kind": "LLMSecurityAnalyzer" - } - ] + "title": "Insert Line", + "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`." }, - "condenser": { + "view_range": { "anyOf": [ { - "$ref": "#/components/schemas/CondenserBase" + "items": { + "type": "integer" + }, + "type": "array" }, { "type": "null" } ], - "title": "Condenser", - "description": "Optional condenser to use for condensing conversation history.", - "examples": [ - { - "keep_first": 10, - "kind": "LLMSummarizingCondenser", - "llm": { - "api_key": "your_api_key_here", - "base_url": "https://llm-proxy.eval.all-hands.dev", - "model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929" - }, - "max_size": 80 - } - ] + "title": "View Range", + "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." + }, + "kind": { + "type": "string", + "const": "PlanningFileEditorAction", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "llm" - ], - "title": "Agent" + "required": ["command", "path", "kind"], + "title": "PlanningFileEditorAction", + "description": "Schema for planning file editor operations.\n\nInherits from FileEditorAction but restricts editing to PLAN.md only.\nAllows viewing any file but only editing PLAN.md." }, - "AgentContext-Output": { + "PlanningFileEditorActionWithRisk": { "properties": { - "skills": { - "items": { - "$ref": "#/components/schemas/Skill" - }, - "type": "array", - "title": "Skills", - "description": "List of available skills that can extend the user's input." + "command": { + "type": "string", + "enum": ["view", "create", "str_replace", "insert", "undo_edit"], + "title": "Command", + "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." }, - "system_message_suffix": { + "path": { + "type": "string", + "title": "Path", + "description": "Absolute path to file or directory." + }, + "file_text": { "anyOf": [ { "type": "string" @@ -2159,10 +13862,10 @@ "type": "null" } ], - "title": "System Message Suffix", - "description": "Optional suffix to append to the system prompt." + "title": "File Text", + "description": "Required parameter of `create` command, with the content of the file to be created." }, - "user_message_suffix": { + "old_str": { "anyOf": [ { "type": "string" @@ -2171,167 +13874,95 @@ "type": "null" } ], - "title": "User Message Suffix", - "description": "Optional suffix to append to the user's message." - } - }, - "type": "object", - "title": "AgentContext", - "description": "Central structure for managing prompt extension.\n\nAgentContext unifies all the contextual inputs that shape how the system\nextends and interprets user prompts. It combines both static environment\ndetails and dynamic, user-activated extensions from skills.\n\nSpecifically, it provides:\n- **Repository context / Repo Skills**: Information about the active codebase,\n branches, and repo-specific instructions contributed by repo skills.\n- **Runtime context**: Current execution environment (hosts, working\n directory, secrets, date, etc.).\n- **Conversation instructions**: Optional task- or channel-specific rules\n that constrain or guide the agent’s behavior across the session.\n- **Knowledge Skills**: Extensible components that can be triggered by user input\n to inject knowledge or domain-specific guidance.\n\nTogether, these elements make AgentContext the primary container responsible\nfor assembling, formatting, and injecting all prompt-relevant context into\nLLM interactions." - }, - "AgentErrorEvent": { - "properties": { - "kind": { - "type": "string", - "const": "AgentErrorEvent", - "title": "Kind", - "default": "AgentErrorEvent" - }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" + "title": "Old Str", + "description": "Required parameter of `str_replace` command containing the string in `path` to replace." }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" + "new_str": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } ], - "title": "Source", - "default": "agent" - }, - "tool_name": { - "type": "string", - "title": "Tool Name", - "description": "The tool name that this observation is responding to" - }, - "tool_call_id": { - "type": "string", - "title": "Tool Call Id", - "description": "The tool call id that this observation is responding to" + "title": "New Str", + "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." }, - "error": { - "type": "string", - "title": "Error", - "description": "The error message from the scaffold" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "tool_name", - "tool_call_id", - "error" - ], - "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": { - "type": "string", - "const": "AlwaysConfirm", - "title": "Kind", - "default": "AlwaysConfirm" - } - }, - "type": "object", - "title": "AlwaysConfirm" - }, - "BashCommand": { - "properties": { - "command": { - "type": "string", - "title": "Command", - "description": "The bash command to execute" + "insert_line": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Insert Line", + "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`." }, - "cwd": { + "view_range": { "anyOf": [ { - "type": "string" + "items": { + "type": "integer" + }, + "type": "array" }, { "type": "null" } ], - "title": "Cwd", - "description": "The current working directory" + "title": "View Range", + "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." }, - "timeout": { - "type": "integer", - "title": "Timeout", - "description": "The max number of seconds a command may be permitted to run.", - "default": 300 + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" }, "kind": { "type": "string", - "const": "BashCommand", - "title": "Kind", - "default": "BashCommand" - }, - "id": { - "type": "string", - "format": "uuid", - "title": "Id" - }, - "timestamp": { - "type": "string", - "format": "date-time", - "title": "Timestamp" + "const": "PlanningFileEditorActionWithRisk", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "command" - ], - "title": "BashCommand" + "required": ["command", "path", "kind"], + "title": "PlanningFileEditorActionWithRisk" }, - "BashEventPage": { + "PlanningFileEditorObservation": { "properties": { - "items": { + "content": { "items": { - "oneOf": [ + "anyOf": [ { - "$ref": "#/components/schemas/BashCommand" + "$ref": "#/components/schemas/TextContent" }, { - "$ref": "#/components/schemas/BashOutput" - } - ], - "title": "BashEventBase", - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__agent_server__models__BashCommand-Output__1": "#/components/schemas/BashCommand", - "openhands__agent_server__models__BashOutput-Output__1": "#/components/schemas/BashOutput" + "$ref": "#/components/schemas/ImageContent" } - } + ] }, "type": "array", - "title": "Items" + "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." }, - "next_page_id": { + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false + }, + "command": { + "type": "string", + "enum": ["view", "create", "str_replace", "insert", "undo_edit"], + "title": "Command", + "description": "The command that was run: `view`, `create`, `str_replace`, `insert`, or `undo_edit`." + }, + "path": { "anyOf": [ { "type": "string" @@ -2340,278 +13971,201 @@ "type": "null" } ], - "title": "Next Page Id" + "title": "Path", + "description": "The file path that was edited." + }, + "prev_exist": { + "type": "boolean", + "title": "Prev Exist", + "description": "Indicates if the file previously existed. If not, it was created.", + "default": true + }, + "old_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Old Content", + "description": "The content of the file before the edit." + }, + "new_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "New Content", + "description": "The content of the file after the edit." + }, + "kind": { + "type": "string", + "const": "PlanningFileEditorObservation", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "items" - ], - "title": "BashEventPage" + "required": ["command", "kind"], + "title": "PlanningFileEditorObservation", + "description": "Observation from planning file editor operations.\n\nInherits from FileEditorObservation - same structure, just different type." }, - "BashEventSortOrder": { - "type": "string", - "enum": [ - "TIMESTAMP", - "TIMESTAMP_DESC" - ], - "title": "BashEventSortOrder" - }, - "BashOutput": { + "PlanningFileEditorTool": { "properties": { - "kind": { - "type": "string", - "const": "BashOutput", - "title": "Kind", - "default": "BashOutput" - }, - "id": { - "type": "string", - "format": "uuid", - "title": "Id" - }, - "timestamp": { + "description": { "type": "string", - "format": "date-time", - "title": "Timestamp" + "title": "Description" }, - "command_id": { + "action_type": { "type": "string", - "format": "uuid", - "title": "Command Id" + "title": "Action Type" }, - "order": { - "type": "integer", - "title": "Order", - "description": "The order for this output, sequentially starting with 0", - "default": 0 - }, - "exit_code": { + "observation_type": { "anyOf": [ { - "type": "integer" + "type": "string" }, { "type": "null" } ], - "title": "Exit Code", - "description": "Exit code None implies the command is still running." + "title": "Observation Type" }, - "stdout": { + "annotations": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" }, { "type": "null" } - ], - "title": "Stdout", - "description": "The standard output from the command" + ] }, - "stderr": { + "meta": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Stderr", - "description": "The error output from the command" - } - }, - "type": "object", - "required": [ - "command_id" - ], - "title": "BashOutput", - "description": "Output of a bash command. A single command may have multiple pieces of output\ndepending on how large the output is." - }, - "Body_upload_file_api_file_upload__path__post": { - "properties": { - "file": { - "type": "string", - "format": "binary", - "title": "File" - } - }, - "type": "object", - "required": [ - "file" - ], - "title": "Body_upload_file_api_file_upload__path__post" - }, - "BrowserClickAction": { - "properties": { - "kind": { - "type": "string", - "const": "BrowserClickAction", - "title": "Kind", - "default": "BrowserClickAction" - }, - "index": { - "type": "integer", - "minimum": 0.0, - "title": "Index", - "description": "The index of the element to click (from browser_get_state)" + "title": "Meta" }, - "new_tab": { - "type": "boolean", - "title": "New Tab", - "description": "Whether to open any resulting navigation in a new tab. Default: False", - "default": false - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "index" - ], - "title": "BrowserClickAction", - "description": "Schema for clicking elements." - }, - "BrowserCloseTabAction": { - "properties": { "kind": { "type": "string", - "const": "BrowserCloseTabAction", - "title": "Kind", - "default": "BrowserCloseTabAction" + "const": "PlanningFileEditorTool", + "title": "Kind" }, - "tab_id": { - "type": "string", - "title": "Tab Id", - "description": "4 Character Tab ID of the tab to close (from browser_list_tabs)" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "tab_id" - ], - "title": "BrowserCloseTabAction", - "description": "Schema for closing browser tabs." - }, - "BrowserGetContentAction": { - "properties": { - "kind": { + "title": { "type": "string", - "const": "BrowserGetContentAction", - "title": "Kind", - "default": "BrowserGetContentAction" - }, - "extract_links": { - "type": "boolean", - "title": "Extract Links", - "description": "Whether to include links in the content (default: False)", - "default": false - }, - "start_from_char": { - "type": "integer", - "minimum": 0.0, - "title": "Start From Char", - "description": "Character index to start from in the page content (default: 0)", - "default": 0 + "title": "Title", + "readOnly": true } }, - "additionalProperties": false, "type": "object", - "title": "BrowserGetContentAction", - "description": "Schema for getting page content in markdown." + "required": ["description", "action_type", "kind", "title"], + "title": "PlanningFileEditorTool", + "description": "A planning file editor tool with read-all, edit-PLAN.md-only access." }, - "BrowserGetStateAction": { + "PluginSource": { "properties": { - "kind": { + "source": { "type": "string", - "const": "BrowserGetStateAction", - "title": "Kind", - "default": "BrowserGetStateAction" + "title": "Source", + "description": "Plugin source: 'github:owner/repo', any git URL, or local path" }, - "include_screenshot": { - "type": "boolean", - "title": "Include Screenshot", - "description": "Whether to include a screenshot of the current page. Default: False", - "default": false + "ref": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Ref", + "description": "Optional branch, tag, or commit (only for git sources)" + }, + "repo_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Repo Path", + "description": "Subdirectory path within the git repository (e.g., 'plugins/my-plugin' for monorepos). Only relevant for git sources, not local paths." } }, - "additionalProperties": false, "type": "object", - "title": "BrowserGetStateAction", - "description": "Schema for getting browser state." + "required": ["source"], + "title": "PluginSource", + "description": "Specification for a plugin to load.\n\nThis model describes where to find a plugin and is used by load_plugins()\nto fetch and load plugins from various sources.\n\nExamples:\n >>> # GitHub repository\n >>> PluginSource(source=\"github:owner/repo\", ref=\"v1.0.0\")\n\n >>> # Plugin from monorepo subdirectory\n >>> PluginSource(\n ... source=\"github:owner/monorepo\",\n ... repo_path=\"plugins/my-plugin\"\n ... )\n\n >>> # Local path\n >>> PluginSource(source=\"/path/to/plugin\")" }, - "BrowserGoBackAction": { + "PolicyRailSecurityAnalyzer-Input": { "properties": { "kind": { "type": "string", - "const": "BrowserGoBackAction", - "title": "Kind", - "default": "BrowserGoBackAction" + "const": "PolicyRailSecurityAnalyzer", + "title": "Kind" } }, - "additionalProperties": false, "type": "object", - "title": "BrowserGoBackAction", - "description": "Schema for going back in browser history." + "title": "PolicyRailSecurityAnalyzer", + "description": "Catch composed threats that plain regex signatures would miss.\n\nUse this when you need to detect threats defined by *combinations*\nof tokens (e.g., ``curl`` piped to ``bash``) rather than individual\nsignatures. While these rails *could* each be expressed as a single\nregex, keeping them as named rules with per-segment evaluation makes\nthe threat model more interpretable, the rules easier to maintain,\nand the audit trail clearer than a flat pattern list.\n\nEvaluates normalized executable segments only -- reasoning text is\nnever scanned.\n\nReturns ``SecurityRisk.HIGH`` when a rail fires, ``LOW`` otherwise.\nPair with ``ConfirmRisky`` and compose via ``EnsembleSecurityAnalyzer``.\n\nv1 rails: fetch-to-exec, raw-disk-op, catastrophic-delete.\n\nExample::\n\n from openhands.sdk.security import PolicyRailSecurityAnalyzer\n\n analyzer = PolicyRailSecurityAnalyzer()\n # risk = analyzer.security_risk(action)" }, - "BrowserListTabsAction": { + "PolicyRailSecurityAnalyzer-Output": { "properties": { "kind": { "type": "string", - "const": "BrowserListTabsAction", - "title": "Kind", - "default": "BrowserListTabsAction" + "const": "PolicyRailSecurityAnalyzer", + "title": "Kind" } }, - "additionalProperties": false, "type": "object", - "title": "BrowserListTabsAction", - "description": "Schema for listing browser tabs." + "required": ["kind"], + "title": "PolicyRailSecurityAnalyzer", + "description": "Catch composed threats that plain regex signatures would miss.\n\nUse this when you need to detect threats defined by *combinations*\nof tokens (e.g., ``curl`` piped to ``bash``) rather than individual\nsignatures. While these rails *could* each be expressed as a single\nregex, keeping them as named rules with per-segment evaluation makes\nthe threat model more interpretable, the rules easier to maintain,\nand the audit trail clearer than a flat pattern list.\n\nEvaluates normalized executable segments only -- reasoning text is\nnever scanned.\n\nReturns ``SecurityRisk.HIGH`` when a rail fires, ``LOW`` otherwise.\nPair with ``ConfirmRisky`` and compose via ``EnsembleSecurityAnalyzer``.\n\nv1 rails: fetch-to-exec, raw-disk-op, catastrophic-delete.\n\nExample::\n\n from openhands.sdk.security import PolicyRailSecurityAnalyzer\n\n analyzer = PolicyRailSecurityAnalyzer()\n # risk = analyzer.security_risk(action)" }, - "BrowserNavigateAction": { + "ProfileDetailResponse": { "properties": { - "kind": { + "name": { "type": "string", - "const": "BrowserNavigateAction", - "title": "Kind", - "default": "BrowserNavigateAction" + "title": "Name" }, - "url": { - "type": "string", - "title": "Url", - "description": "The URL to navigate to" + "config": { + "additionalProperties": true, + "type": "object", + "title": "Config" }, - "new_tab": { + "api_key_set": { "type": "boolean", - "title": "New Tab", - "description": "Whether to open in a new tab. Default: False", + "title": "Api Key Set", "default": false } }, - "additionalProperties": false, "type": "object", - "required": [ - "url" - ], - "title": "BrowserNavigateAction", - "description": "Schema for browser navigation." + "required": ["name", "config"], + "title": "ProfileDetailResponse", + "description": "``config.api_key`` is always nulled; use ``api_key_set`` instead." }, - "BrowserObservation": { + "ProfileInfo": { "properties": { - "kind": { - "type": "string", - "const": "BrowserObservation", - "title": "Kind", - "default": "BrowserObservation" - }, - "output": { + "name": { "type": "string", - "title": "Output", - "description": "The output message from the browser operation" + "title": "Name" }, - "error": { + "model": { "anyOf": [ { "type": "string" @@ -2620,10 +14174,9 @@ "type": "null" } ], - "title": "Error", - "description": "Error message if any" + "title": "Model" }, - "screenshot_data": { + "base_url": { "anyOf": [ { "type": "string" @@ -2632,191 +14185,264 @@ "type": "null" } ], - "title": "Screenshot Data", - "description": "Base64 screenshot data if available" + "title": "Base Url" + }, + "api_key_set": { + "type": "boolean", + "title": "Api Key Set", + "default": false } }, - "additionalProperties": false, "type": "object", - "required": [ - "output" - ], - "title": "BrowserObservation", - "description": "Base observation for browser operations." + "required": ["name"], + "title": "ProfileInfo" }, - "BrowserScrollAction": { + "ProfileListResponse": { "properties": { - "kind": { - "type": "string", - "const": "BrowserScrollAction", - "title": "Kind", - "default": "BrowserScrollAction" + "profiles": { + "items": { + "$ref": "#/components/schemas/ProfileInfo" + }, + "type": "array", + "title": "Profiles" }, - "direction": { - "type": "string", - "enum": [ - "up", - "down" + "active_profile": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } ], - "title": "Direction", - "description": "Direction to scroll. Options: 'up', 'down'. Default: 'down'", - "default": "down" + "title": "Active Profile" } }, - "additionalProperties": false, "type": "object", - "title": "BrowserScrollAction", - "description": "Schema for scrolling the page." + "required": ["profiles"], + "title": "ProfileListResponse" }, - "BrowserSwitchTabAction": { + "ProfileMutationResponse": { "properties": { - "kind": { + "name": { "type": "string", - "const": "BrowserSwitchTabAction", - "title": "Kind", - "default": "BrowserSwitchTabAction" + "title": "Name" }, - "tab_id": { + "message": { "type": "string", - "title": "Tab Id", - "description": "4 Character Tab ID of the tab to switch to (from browser_list_tabs)" + "title": "Message" } }, - "additionalProperties": false, "type": "object", - "required": [ - "tab_id" - ], - "title": "BrowserSwitchTabAction", - "description": "Schema for switching browser tabs." + "required": ["name", "message"], + "title": "ProfileMutationResponse" }, - "BrowserTypeAction": { + "ProvidersResponse": { "properties": { - "kind": { - "type": "string", - "const": "BrowserTypeAction", - "title": "Kind", - "default": "BrowserTypeAction" - }, - "index": { - "type": "integer", - "minimum": 0.0, - "title": "Index", - "description": "The index of the input element (from browser_get_state)" - }, - "text": { - "type": "string", - "title": "Text", - "description": "The text to type" + "providers": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Providers" } }, - "additionalProperties": false, "type": "object", - "required": [ - "index", - "text" - ], - "title": "BrowserTypeAction", - "description": "Schema for typing text into elements." + "required": ["providers"], + "title": "ProvidersResponse", + "description": "Response containing the list of available LLM providers." }, - "ChatCompletionCachedContent": { + "ReadFileAction": { "properties": { - "type": { + "file_path": { "type": "string", - "const": "ephemeral", - "title": "Type" + "title": "File Path", + "description": "The path to the file to read." + }, + "offset": { + "anyOf": [ + { + "type": "integer", + "minimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Offset", + "description": "Optional: The 0-based line number to start reading from. Use for paginating through large files." + }, + "limit": { + "anyOf": [ + { + "type": "integer", + "minimum": 1.0 + }, + { + "type": "null" + } + ], + "title": "Limit", + "description": "Optional: Maximum number of lines to read. Use with 'offset' to paginate through large files." + }, + "kind": { + "type": "string", + "const": "ReadFileAction", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "type" - ], - "title": "ChatCompletionCachedContent" + "required": ["file_path", "kind"], + "title": "ReadFileAction", + "description": "Schema for read file operation." }, - "ChatCompletionToolParam": { + "ReadFileActionWithRisk": { "properties": { - "type": { + "file_path": { + "type": "string", + "title": "File Path", + "description": "The path to the file to read." + }, + "offset": { "anyOf": [ { - "type": "string", - "const": "function" + "type": "integer", + "minimum": 0.0 }, { - "type": "string" + "type": "null" } ], - "title": "Type" + "title": "Offset", + "description": "Optional: The 0-based line number to start reading from. Use for paginating through large files." + }, + "limit": { + "anyOf": [ + { + "type": "integer", + "minimum": 1.0 + }, + { + "type": "null" + } + ], + "title": "Limit", + "description": "Optional: Maximum number of lines to read. Use with 'offset' to paginate through large files." }, - "function": { - "$ref": "#/components/schemas/ChatCompletionToolParamFunctionChunk" + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" }, - "cache_control": { - "$ref": "#/components/schemas/ChatCompletionCachedContent" + "kind": { + "type": "string", + "const": "ReadFileActionWithRisk", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "type", - "function" - ], - "title": "ChatCompletionToolParam" + "required": ["file_path", "kind"], + "title": "ReadFileActionWithRisk" }, - "ChatCompletionToolParamFunctionChunk": { + "ReadFileObservation": { "properties": { - "name": { - "type": "string", - "title": "Name" + "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." }, - "description": { + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false + }, + "file_path": { "type": "string", - "title": "Description" + "title": "File Path", + "description": "The file path that was read." }, - "parameters": { - "additionalProperties": true, - "type": "object", - "title": "Parameters" + "file_content": { + "type": "string", + "title": "File Content", + "description": "The content read from the file.", + "default": "" }, - "strict": { + "is_truncated": { "type": "boolean", - "title": "Strict" + "title": "Is Truncated", + "description": "Whether the content was truncated due to size limits.", + "default": false + }, + "lines_shown": { + "anyOf": [ + { + "prefixItems": [ + { + "type": "integer" + }, + { + "type": "integer" + } + ], + "type": "array", + "maxItems": 2, + "minItems": 2 + }, + { + "type": "null" + } + ], + "title": "Lines Shown", + "description": "If truncated, the range of lines shown (start, end) - 1-indexed." + }, + "total_lines": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Total Lines", + "description": "Total number of lines in the file." + }, + "kind": { + "type": "string", + "const": "ReadFileObservation", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "name" - ], - "title": "ChatCompletionToolParamFunctionChunk" + "required": ["file_path", "kind"], + "title": "ReadFileObservation", + "description": "Observation from reading a file." }, - "CmdOutputMetadata": { + "ReadFileTool": { "properties": { - "exit_code": { - "type": "integer", - "title": "Exit Code", - "description": "The exit code of the last executed command.", - "default": -1 - }, - "pid": { - "type": "integer", - "title": "Pid", - "description": "The process ID of the last executed command.", - "default": -1 + "description": { + "type": "string", + "title": "Description" }, - "username": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Username", - "description": "The username of the current user." + "action_type": { + "type": "string", + "title": "Action Type" }, - "hostname": { + "observation_type": { "anyOf": [ { "type": "string" @@ -2825,297 +14451,139 @@ "type": "null" } ], - "title": "Hostname", - "description": "The hostname of the machine." + "title": "Observation Type" }, - "working_dir": { + "annotations": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" }, { "type": "null" } - ], - "title": "Working Dir", - "description": "The current working directory." + ] }, - "py_interpreter_path": { + "meta": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Py Interpreter Path", - "description": "The path to the current Python interpreter, if any." + "title": "Meta" }, - "prefix": { + "kind": { "type": "string", - "title": "Prefix", - "description": "Prefix to add to command output", - "default": "" + "const": "ReadFileTool", + "title": "Kind" }, - "suffix": { + "title": { "type": "string", - "title": "Suffix", - "description": "Suffix to add to command output", - "default": "" + "title": "Title", + "readOnly": true } }, "type": "object", - "title": "CmdOutputMetadata", - "description": "Additional metadata captured from PS1" + "required": ["description", "action_type", "kind", "title"], + "title": "ReadFileTool", + "description": "Tool for reading file contents with pagination support." }, - "Condensation": { + "ReasoningItemModel": { "properties": { - "kind": { - "type": "string", - "const": "Condensation", - "title": "Kind", - "default": "Condensation" - }, "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" - }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } ], - "title": "Source", - "default": "environment" + "title": "Id" }, - "forgotten_event_ids": { + "summary": { "items": { "type": "string" }, "type": "array", - "title": "Forgotten Event Ids", - "description": "The IDs of the events that are being forgotten (removed from the `View` given to the LLM)." + "title": "Summary" }, - "summary": { + "content": { "anyOf": [ { - "type": "string" + "items": { + "type": "string" + }, + "type": "array" }, { "type": "null" } ], - "title": "Summary", - "description": "An optional summary of the events being forgotten." + "title": "Content" }, - "summary_offset": { + "encrypted_content": { "anyOf": [ { - "type": "integer", - "minimum": 0.0 + "type": "string" }, { "type": "null" } ], - "title": "Summary Offset", - "description": "An optional offset to the start of the resulting view indicating where the summary should be inserted." - } - }, - "additionalProperties": false, - "type": "object", - "title": "Condensation", - "description": "This action indicates a condensation of the conversation history is happening." - }, - "CondensationRequest": { - "properties": { - "kind": { - "type": "string", - "const": "CondensationRequest", - "title": "Kind", - "default": "CondensationRequest" - }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" - }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" - ], - "title": "Source", - "default": "environment" - } - }, - "additionalProperties": false, - "type": "object", - "title": "CondensationRequest", - "description": "This action is used to request a condensation of the conversation history.\n\nAttributes:\n action (str): The action type, namely ActionType.CONDENSATION_REQUEST." - }, - "CondensationSummaryEvent": { - "properties": { - "kind": { - "type": "string", - "const": "CondensationSummaryEvent", - "title": "Kind", - "default": "CondensationSummaryEvent" - }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" + "title": "Encrypted Content" }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" + "status": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } ], - "title": "Source", - "default": "environment" - }, - "summary": { - "type": "string", - "title": "Summary" + "title": "Status" } }, - "additionalProperties": false, "type": "object", - "required": [ - "summary" - ], - "title": "CondensationSummaryEvent", - "description": "This event represents a summary generated by a condenser." + "title": "ReasoningItemModel", + "description": "OpenAI Responses reasoning item (non-stream, subset we consume).\n\nDo not log or render encrypted_content." }, - "ConfirmRisky": { + "RedactedThinkingBlock": { "properties": { - "kind": { + "type": { "type": "string", - "const": "ConfirmRisky", - "title": "Kind", - "default": "ConfirmRisky" - }, - "threshold": { - "$ref": "#/components/schemas/SecurityRisk", - "default": "HIGH" - }, - "confirm_unknown": { - "type": "boolean", - "title": "Confirm Unknown", - "default": true - } - }, - "type": "object", - "title": "ConfirmRisky" - }, - "ConfirmationResponseRequest": { - "properties": { - "accept": { - "type": "boolean", - "title": "Accept" + "const": "redacted_thinking", + "title": "Type", + "default": "redacted_thinking" }, - "reason": { + "data": { "type": "string", - "title": "Reason", - "default": "User rejected the action." + "title": "Data", + "description": "The redacted thinking content" } }, "type": "object", - "required": [ - "accept" - ], - "title": "ConfirmationResponseRequest", - "description": "Payload to accept or reject a pending action." + "required": ["data"], + "title": "RedactedThinkingBlock", + "description": "Redacted thinking block for previous responses without extended thinking.\n\nThis is used as a placeholder for assistant messages that were generated\nbefore extended thinking was enabled." }, - "ConversationInfo": { - "properties": { - "id": { - "type": "string", - "format": "uuid", - "title": "Id", - "description": "Unique conversation ID" - }, - "agent": { - "$ref": "#/components/schemas/Agent-Output", - "description": "The agent running in the conversation. This is persisted to allow resuming conversations and check agent configuration to handle e.g., tool changes, LLM changes, etc." - }, - "workspace": { - "$ref": "#/components/schemas/BaseWorkspace" - }, - "persistence_dir": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Persistence Dir", - "description": "Directory for persisting conversation state and events. If None, conversation will not be persisted.", - "default": "workspace/conversations" - }, - "max_iterations": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Max Iterations", - "description": "Maximum number of iterations the agent can perform in a single run.", - "default": 500 - }, - "stuck_detection": { - "type": "boolean", - "title": "Stuck Detection", - "description": "Whether to enable stuck detection for the agent.", - "default": true - }, - "agent_status": { - "$ref": "#/components/schemas/AgentExecutionStatus", - "default": "idle" - }, - "confirmation_policy": { - "$ref": "#/components/schemas/ConfirmationPolicyBase" - }, - "activated_knowledge_skills": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Activated Knowledge Skills", - "description": "List of activated knowledge skills name" - }, - "stats": { - "$ref": "#/components/schemas/ConversationStats-Output", - "description": "Conversation statistics for tracking LLM metrics" + "RemoteWorkspace": { + "properties": { + "working_dir": { + "type": "string", + "title": "Working Dir", + "description": "The working directory for agent operations and tool execution." }, - "secrets_manager": { - "$ref": "#/components/schemas/SecretsManager-Output", - "description": "Manager for handling secrets and sensitive data" + "host": { + "type": "string", + "title": "Host", + "description": "The remote host URL for the workspace." }, - "title": { + "api_key": { "anyOf": [ { "type": "string" @@ -3124,162 +14592,141 @@ "type": "null" } ], - "title": "Title", - "description": "User-defined title for the conversation" + "title": "Api Key", + "description": "API key for authenticating with the remote host." }, - "metrics": { + "read_timeout": { + "type": "number", + "title": "Read Timeout", + "description": "Timeout in seconds for reading operations of httpx.Client.", + "default": 600.0 + }, + "max_connections": { "anyOf": [ { - "$ref": "#/components/schemas/MetricsSnapshot" + "type": "integer" }, { "type": "null" } - ] - }, - "created_at": { - "type": "string", - "format": "date-time", - "title": "Created At" + ], + "title": "Max Connections", + "description": "Maximum number of connections for httpx.Client. None means no limit, useful for running many conversations in parallel." }, - "updated_at": { + "kind": { "type": "string", - "format": "date-time", - "title": "Updated At" + "const": "RemoteWorkspace", + "title": "Kind" } }, "type": "object", - "required": [ - "id", - "agent", - "workspace" - ], - "title": "ConversationInfo", - "description": "Information about a conversation running locally without a Runtime sandbox." + "required": ["working_dir", "host", "kind"], + "title": "RemoteWorkspace", + "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\nSupports optional completion callbacks on exit via environment variables:\n - ``AUTOMATION_CALLBACK_URL`` — URL to POST completion status to\n - ``AUTOMATION_CALLBACK_API_KEY`` — Bearer token for callback auth (optional)\n - ``AUTOMATION_RUN_ID`` — Run ID to include in callback payload (optional)\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\")" }, - "ConversationPage": { + "RenameProfileRequest": { "properties": { - "items": { - "items": { - "$ref": "#/components/schemas/ConversationInfo" - }, - "type": "array", - "title": "Items" - }, - "next_page_id": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Next Page Id" + "new_name": { + "type": "string", + "maxLength": 64, + "minLength": 1, + "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$", + "title": "New Name" } }, "type": "object", - "required": [ - "items" - ], - "title": "ConversationPage" - }, - "ConversationSortOrder": { - "type": "string", - "enum": [ - "CREATED_AT", - "UPDATED_AT", - "CREATED_AT_DESC", - "UPDATED_AT_DESC" - ], - "title": "ConversationSortOrder", - "description": "Enum for conversation sorting options." + "required": ["new_name"], + "title": "RenameProfileRequest" }, - "ConversationStateUpdateEvent": { + "ResponseLatency": { "properties": { - "kind": { - "type": "string", - "const": "ConversationStateUpdateEvent", - "title": "Kind", - "default": "ConversationStateUpdateEvent" - }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { + "model": { "type": "string", - "title": "Timestamp", - "description": "Event timestamp" + "title": "Model" }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" - ], - "title": "Source", - "default": "environment" + "latency": { + "type": "number", + "minimum": 0.0, + "title": "Latency", + "description": "Latency must be non-negative" }, - "key": { + "response_id": { "type": "string", - "title": "Key", - "description": "Unique key for this state update event" - }, - "value": { - "title": "Value", - "description": "Serialized conversation state updates" + "title": "Response Id" } }, - "additionalProperties": false, "type": "object", - "title": "ConversationStateUpdateEvent", - "description": "Event that contains conversation state updates.\n\nThis event is sent via websocket whenever the conversation state changes,\nallowing remote clients to stay in sync without making REST API calls.\n\nAll fields are serialized versions of the corresponding ConversationState fields\nto ensure compatibility with websocket transmission." + "required": ["model", "latency", "response_id"], + "title": "ResponseLatency", + "description": "Metric tracking the round-trip time per completion call." }, - "ConversationStats-Output": { + "SandboxConfig": { "properties": { - "usage_to_metrics": { - "additionalProperties": { - "$ref": "#/components/schemas/Metrics" + "exposed_urls": { + "items": { + "$ref": "#/components/schemas/ExposedUrl" }, - "type": "object", - "title": "Usage To Metrics", - "description": "Active usage metrics tracked by the registry." + "type": "array", + "title": "Exposed Urls", + "description": "List of exposed URLs from the sandbox" } }, "type": "object", - "title": "ConversationStats", - "description": "Track per-LLM usage metrics observed during conversations." + "title": "SandboxConfig", + "description": "Configuration for loading sandbox-specific skills." }, - "Cost": { + "SaveProfileRequest": { "properties": { - "model": { + "llm": { + "$ref": "#/components/schemas/LLM-Input" + }, + "include_secrets": { + "type": "boolean", + "title": "Include Secrets", + "description": "Whether to persist the API key with the profile.", + "default": true + } + }, + "type": "object", + "required": ["llm"], + "title": "SaveProfileRequest" + }, + "SecretCreateRequest": { + "properties": { + "name": { "type": "string", - "title": "Model" + "title": "Name" }, - "cost": { - "type": "number", - "minimum": 0.0, - "title": "Cost", - "description": "Cost must be non-negative" + "value": { + "type": "string", + "format": "password", + "title": "Value", + "writeOnly": true }, - "timestamp": { - "type": "number", - "title": "Timestamp" + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description" } }, "type": "object", - "required": [ - "model", - "cost" - ], - "title": "Cost" + "required": ["name", "value"], + "title": "SecretCreateRequest", + "description": "Request model for PUT /api/settings/secrets.\n\nCreates or updates a secret with the given name and value." }, - "DesktopUrlResponse": { + "SecretItemResponse": { "properties": { - "url": { + "name": { + "type": "string", + "title": "Name" + }, + "description": { "anyOf": [ { "type": "string" @@ -3288,776 +14735,607 @@ "type": "null" } ], - "title": "Url" + "title": "Description" } }, "type": "object", - "required": [ - "url" + "required": ["name"], + "title": "SecretItemResponse", + "description": "Response model for a secret item (without value).\n\nUsed in list responses and as the response for create/update operations." + }, + "SecretRegistry": { + "properties": { + "secret_sources": { + "additionalProperties": { + "$ref": "#/components/schemas/SecretSource-Output" + }, + "type": "object", + "title": "Secret Sources" + } + }, + "type": "object", + "title": "SecretRegistry", + "description": "Manages secrets and injects them into bash commands when needed.\n\nThe secret registry stores a mapping of secret keys to SecretSources\nthat retrieve the actual secret values. When a bash command is about to be\nexecuted, it scans the command for any secret keys and injects the corresponding\nenvironment variables.\n\nSecret sources will redact / encrypt their sensitive values as appropriate when\nserializing, depending on the content of the context. If a context is present\nand contains a 'cipher' object, this is used for encryption. If it contains a\nboolean 'expose_secrets' flag set to True, secrets are dunped in plain text.\nOtherwise secrets are redacted.\n\nAdditionally, it tracks the latest exported values to enable consistent masking\neven when callable secrets fail on subsequent calls." + }, + "SecretSource-Input": { + "oneOf": [ + { + "$ref": "#/components/schemas/LookupSecret-Input" + }, + { + "$ref": "#/components/schemas/StaticSecret-Input" + } ], - "title": "DesktopUrlResponse", - "description": "Response model for Desktop URL." + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__secret__secrets__LookupSecret-Input__1": "#/components/schemas/LookupSecret-Input", + "openhands__sdk__secret__secrets__StaticSecret-Input__1": "#/components/schemas/StaticSecret-Input" + } + } }, - "EventPage": { + "SecretSource-Output": { + "oneOf": [ + { + "$ref": "#/components/schemas/LookupSecret-Output" + }, + { + "$ref": "#/components/schemas/StaticSecret-Output" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__secret__secrets__LookupSecret-Output__1": "#/components/schemas/LookupSecret-Output", + "openhands__sdk__secret__secrets__StaticSecret-Output__1": "#/components/schemas/StaticSecret-Output" + } + } + }, + "SecretsListResponse": { "properties": { - "items": { + "secrets": { "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/Condensation" - }, - { - "$ref": "#/components/schemas/CondensationRequest" - }, - { - "$ref": "#/components/schemas/CondensationSummaryEvent" - }, - { - "$ref": "#/components/schemas/ConversationStateUpdateEvent" - }, - { - "$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/PauseEvent" - } - ], - "title": "Event", - "discriminator": { - "propertyName": "kind", - "mapping": { - "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_state__ConversationStateUpdateEvent-Output__1": "#/components/schemas/ConversationStateUpdateEvent", - "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__user_action__PauseEvent-Output__1": "#/components/schemas/PauseEvent" - } - } + "$ref": "#/components/schemas/SecretItemResponse" }, "type": "array", - "title": "Items" + "title": "Secrets" + } + }, + "type": "object", + "required": ["secrets"], + "title": "SecretsListResponse", + "description": "Response model for GET /api/settings/secrets.\n\nLists all available secrets with their names and descriptions.\nValues are never included in list responses." + }, + "SecurityAnalyzerBase-Input": { + "oneOf": [ + { + "$ref": "#/components/schemas/PatternSecurityAnalyzer-Input" + }, + { + "$ref": "#/components/schemas/PolicyRailSecurityAnalyzer-Input" + }, + { + "$ref": "#/components/schemas/EnsembleSecurityAnalyzer-Input" + }, + { + "$ref": "#/components/schemas/GraySwanAnalyzer-Input" + }, + { + "$ref": "#/components/schemas/LLMSecurityAnalyzer-Input" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__security__defense_in_depth__pattern__PatternSecurityAnalyzer-Input__1": "#/components/schemas/PatternSecurityAnalyzer-Input", + "openhands__sdk__security__defense_in_depth__policy_rails__PolicyRailSecurityAnalyzer-Input__1": "#/components/schemas/PolicyRailSecurityAnalyzer-Input", + "openhands__sdk__security__ensemble__EnsembleSecurityAnalyzer-Input__1": "#/components/schemas/EnsembleSecurityAnalyzer-Input", + "openhands__sdk__security__grayswan__analyzer__GraySwanAnalyzer-Input__1": "#/components/schemas/GraySwanAnalyzer-Input", + "openhands__sdk__security__llm_analyzer__LLMSecurityAnalyzer-Input__1": "#/components/schemas/LLMSecurityAnalyzer-Input" + } + } + }, + "SecurityAnalyzerBase-Output": { + "oneOf": [ + { + "$ref": "#/components/schemas/PatternSecurityAnalyzer-Output" + }, + { + "$ref": "#/components/schemas/PolicyRailSecurityAnalyzer-Output" + }, + { + "$ref": "#/components/schemas/EnsembleSecurityAnalyzer-Output" + }, + { + "$ref": "#/components/schemas/GraySwanAnalyzer-Output" }, - "next_page_id": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Next Page Id" + { + "$ref": "#/components/schemas/LLMSecurityAnalyzer-Output" } - }, - "type": "object", - "required": [ - "items" ], - "title": "EventPage" + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__security__defense_in_depth__pattern__PatternSecurityAnalyzer-Output__1": "#/components/schemas/PatternSecurityAnalyzer-Output", + "openhands__sdk__security__defense_in_depth__policy_rails__PolicyRailSecurityAnalyzer-Output__1": "#/components/schemas/PolicyRailSecurityAnalyzer-Output", + "openhands__sdk__security__ensemble__EnsembleSecurityAnalyzer-Output__1": "#/components/schemas/EnsembleSecurityAnalyzer-Output", + "openhands__sdk__security__grayswan__analyzer__GraySwanAnalyzer-Output__1": "#/components/schemas/GraySwanAnalyzer-Output", + "openhands__sdk__security__llm_analyzer__LLMSecurityAnalyzer-Output__1": "#/components/schemas/LLMSecurityAnalyzer-Output" + } + } }, - "EventSortOrder": { + "SecurityRisk": { "type": "string", - "enum": [ - "TIMESTAMP", - "TIMESTAMP_DESC" - ], - "title": "EventSortOrder", - "description": "Enum for event sorting options." + "enum": ["UNKNOWN", "LOW", "MEDIUM", "HIGH"], + "title": "SecurityRisk", + "description": "Security risk levels for actions.\n\nBased on OpenHands security risk levels but adapted for agent-sdk.\nInteger values allow for easy comparison and ordering." }, - "ExecuteBashAction": { + "SendMessageRequest": { "properties": { - "kind": { - "type": "string", - "const": "ExecuteBashAction", - "title": "Kind", - "default": "ExecuteBashAction" - }, - "command": { + "role": { "type": "string", - "title": "Command", - "description": "The bash command to execute. Can be empty string to view additional logs when previous exit code is `-1`. Can be `C-c` (Ctrl+C) to interrupt the currently running process. Note: You can only execute one bash command at a time. If you need to run multiple commands sequentially, you can use `&&` or `;` to chain them together." - }, - "is_input": { - "type": "boolean", - "title": "Is Input", - "description": "If True, the command is an input to the running process. If False, the command is a bash command to be executed in the terminal. Default is False.", - "default": false + "enum": ["user", "system", "assistant", "tool"], + "title": "Role", + "default": "user" }, - "timeout": { - "anyOf": [ - { - "type": "number", - "minimum": 0.0 - }, - { - "type": "null" - } - ], - "title": "Timeout", - "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)." + "content": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TextContent" + }, + { + "$ref": "#/components/schemas/ImageContent" + } + ] + }, + "type": "array", + "title": "Content" }, - "reset": { + "run": { "type": "boolean", - "title": "Reset", - "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": "Run", + "description": "Whether the agent loop should automatically run if not running", "default": false } }, - "additionalProperties": false, "type": "object", - "required": [ - "command" - ], - "title": "ExecuteBashAction", - "description": "Schema for bash command execution." + "title": "SendMessageRequest", + "description": "Payload to send a message to the agent." }, - "ExecuteBashObservation": { + "ServerErrorEvent": { "properties": { - "kind": { + "id": { "type": "string", - "const": "ExecuteBashObservation", - "title": "Kind", - "default": "ExecuteBashObservation" + "title": "Id", + "description": "Unique event id (ULID/UUID)" }, - "output": { + "timestamp": { "type": "string", - "title": "Output", - "description": "The raw output from the tool." - }, - "command": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Command", - "description": "The bash 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": "Timestamp", + "description": "Event timestamp" }, - "exit_code": { - "anyOf": [ - { - "type": "integer" - }, - { - "type": "null" - } - ], - "title": "Exit Code", - "description": "The exit code of the command. -1 indicates the process hit the soft timeout and is not yet finished." + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "description": "The source of this event" }, - "error": { - "type": "boolean", - "title": "Error", - "description": "Whether there was an error during command execution.", - "default": false + "code": { + "type": "string", + "title": "Code", + "description": "Code for the error - typically an error type" }, - "timeout": { - "type": "boolean", - "title": "Timeout", - "description": "Whether the command execution timed out.", - "default": false + "detail": { + "type": "string", + "title": "Detail", + "description": "Details about the error" }, - "metadata": { - "$ref": "#/components/schemas/CmdOutputMetadata", - "description": "Additional metadata captured from PS1 after command execution." + "kind": { + "type": "string", + "const": "ServerErrorEvent", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "output" - ], - "title": "ExecuteBashObservation", - "description": "A ToolResult that can be rendered as a CLI output." + "required": ["source", "code", "detail", "kind"], + "title": "ServerErrorEvent", + "description": "Event emitted by the agent server when a server-level error occurs.\n\nThis event is used for errors that originate from the agent server itself,\nsuch as MCP connection failures, WebSocket errors, or other infrastructure\nissues. Unlike ConversationErrorEvent which is for conversation-level failures,\nthis event indicates a problem with the server environment." }, - "ExecuteBashRequest": { + "ServerInfo": { "properties": { - "command": { - "type": "string", - "title": "Command", - "description": "The bash command to execute" + "uptime": { + "type": "number", + "title": "Uptime" }, - "cwd": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Cwd", - "description": "The current working directory" + "idle_time": { + "type": "number", + "title": "Idle Time" }, - "timeout": { - "type": "integer", - "title": "Timeout", - "description": "The max number of seconds a command may be permitted to run.", - "default": 300 - } - }, - "type": "object", - "required": [ - "command" - ], - "title": "ExecuteBashRequest" - }, - "FileEditorAction": { - "properties": { - "kind": { + "title": { "type": "string", - "const": "FileEditorAction", - "title": "Kind", - "default": "FileEditorAction" + "title": "Title", + "default": "OpenHands Agent Server" }, - "command": { + "version": { "type": "string", - "enum": [ - "view", - "create", - "str_replace", - "insert", - "undo_edit" - ], - "title": "Command", - "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." + "title": "Version" }, - "path": { + "sdk_version": { "type": "string", - "title": "Path", - "description": "Absolute path to file or directory." - }, - "file_text": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "File Text", - "description": "Required parameter of `create` command, with the content of the file to be created." - }, - "old_str": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Old Str", - "description": "Required parameter of `str_replace` command containing the string in `path` to replace." - }, - "new_str": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "New Str", - "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": "Sdk Version" }, - "insert_line": { - "anyOf": [ - { - "type": "integer", - "minimum": 0.0 - }, - { - "type": "null" - } - ], - "title": "Insert Line", - "description": "Required parameter of `insert` command. The `new_str` will be inserted AFTER the line `insert_line` of `path`." + "tools_version": { + "type": "string", + "title": "Tools Version" }, - "view_range": { - "anyOf": [ - { - "items": { - "type": "integer" - }, - "type": "array" - }, - { - "type": "null" - } - ], - "title": "View Range", - "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." - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "command", - "path" - ], - "title": "FileEditorAction", - "description": "Schema for file editor operations." - }, - "FileEditorObservation": { - "properties": { - "kind": { + "workspace_version": { "type": "string", - "const": "FileEditorObservation", - "title": "Kind", - "default": "FileEditorObservation" + "title": "Workspace Version" }, - "command": { + "build_git_sha": { "type": "string", - "enum": [ - "view", - "create", - "str_replace", - "insert", - "undo_edit" - ], - "title": "Command", - "description": "The commands to run. Allowed options are: `view`, `create`, `str_replace`, `insert`, `undo_edit`." + "title": "Build Git Sha" }, - "output": { + "build_git_ref": { "type": "string", - "title": "Output", - "description": "The output message from the tool for the LLM to see.", - "default": "" + "title": "Build Git Ref" }, - "path": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Path", - "description": "The file path that was edited." + "python_version": { + "type": "string", + "title": "Python Version" }, - "prev_exist": { - "type": "boolean", - "title": "Prev Exist", - "description": "Indicates if the file previously existed. If not, it was created.", - "default": true + "usable_tools": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Usable Tools" }, - "old_content": { + "docs": { + "type": "string", + "title": "Docs", + "default": "/docs" + }, + "redoc": { + "type": "string", + "title": "Redoc", + "default": "/redoc" + } + }, + "type": "object", + "required": ["uptime", "idle_time"], + "title": "ServerInfo" + }, + "SetConfirmationPolicyRequest": { + "properties": { + "policy": { + "$ref": "#/components/schemas/ConfirmationPolicyBase-Input", + "description": "The confirmation policy to set" + } + }, + "type": "object", + "required": ["policy"], + "title": "SetConfirmationPolicyRequest", + "description": "Payload to set confirmation policy for a conversation." + }, + "SetSecurityAnalyzerRequest": { + "properties": { + "security_analyzer": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/SecurityAnalyzerBase-Input" }, { "type": "null" } ], - "title": "Old Content", - "description": "The content of the file before the edit." - }, - "new_content": { + "description": "The security analyzer to set" + } + }, + "type": "object", + "required": ["security_analyzer"], + "title": "SetSecurityAnalyzerRequest", + "description": "Payload to set security analyzer for a conversation" + }, + "SettingProminence": { + "type": "string", + "enum": ["critical", "major", "minor"], + "title": "SettingProminence" + }, + "SettingsChoice": { + "properties": { + "value": { "anyOf": [ { - "type": "string" + "type": "boolean" }, { - "type": "null" - } - ], - "title": "New Content", - "description": "The content of the file after the edit." - }, - "error": { - "anyOf": [ + "type": "integer" + }, { - "type": "string" + "type": "number" }, { - "type": "null" + "type": "string" } ], - "title": "Error", - "description": "Error message if any." - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "command" - ], - "title": "FileEditorObservation", - "description": "A ToolResult that can be rendered as a CLI output." - }, - "FinishAction": { - "properties": { - "kind": { - "type": "string", - "const": "FinishAction", - "title": "Kind", - "default": "FinishAction" + "title": "Value" }, - "message": { + "label": { "type": "string", - "title": "Message", - "description": "Final message to send to the user." + "title": "Label" } }, - "additionalProperties": false, "type": "object", - "required": [ - "message" - ], - "title": "FinishAction" + "required": ["value", "label"], + "title": "SettingsChoice" }, - "FinishObservation": { + "SettingsFieldSchema": { "properties": { - "kind": { + "key": { "type": "string", - "const": "FinishObservation", - "title": "Kind", - "default": "FinishObservation" + "title": "Key" }, - "message": { + "label": { "type": "string", - "title": "Message", - "description": "Final message sent to the user." - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "message" - ], - "title": "FinishObservation" - }, - "GenerateTitleRequest": { - "properties": { - "max_length": { - "type": "integer", - "maximum": 200.0, - "minimum": 1.0, - "title": "Max Length", - "description": "Maximum length of the generated title", - "default": 50 + "title": "Label" }, - "llm": { + "description": { "anyOf": [ { - "$ref": "#/components/schemas/LLM" + "type": "string" }, { "type": "null" } ], - "description": "Optional LLM to use for title generation" - } - }, - "type": "object", - "title": "GenerateTitleRequest", - "description": "Payload to generate a title for a conversation." - }, - "GenerateTitleResponse": { - "properties": { - "title": { + "title": "Description" + }, + "section": { "type": "string", - "title": "Title", - "description": "The generated title for the conversation" - } - }, - "type": "object", - "required": [ - "title" - ], - "title": "GenerateTitleResponse", - "description": "Response containing the generated conversation title." - }, - "HTTPValidationError": { - "properties": { - "detail": { + "title": "Section" + }, + "section_label": { + "type": "string", + "title": "Section Label" + }, + "value_type": { + "type": "string", + "enum": ["string", "integer", "number", "boolean", "array", "object"], + "title": "Value Type" + }, + "default": { + "title": "Default" + }, + "prominence": { + "$ref": "#/components/schemas/SettingProminence", + "default": "minor" + }, + "depends_on": { "items": { - "$ref": "#/components/schemas/ValidationError" + "type": "string" }, "type": "array", - "title": "Detail" - } - }, - "type": "object", - "title": "HTTPValidationError" - }, - "ImageContent": { - "properties": { - "cache_prompt": { + "title": "Depends On" + }, + "secret": { "type": "boolean", - "title": "Cache Prompt", + "title": "Secret", "default": false }, - "type": { - "type": "string", - "const": "image", - "title": "Type", - "default": "image" - }, - "image_urls": { + "choices": { "items": { - "type": "string" + "$ref": "#/components/schemas/SettingsChoice" }, "type": "array", - "title": "Image Urls" + "title": "Choices" + }, + "variant": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Variant", + "description": "When set, the field only applies to the named ``AgentSettings`` variant (``'openhands'`` or ``'acp'``). The GUI filters fields by the user's current variant; fields with ``variant=None`` are shown regardless." } }, "type": "object", - "required": [ - "image_urls" - ], - "title": "ImageContent" + "required": ["key", "label", "section", "section_label", "value_type"], + "title": "SettingsFieldSchema" }, - "InputMetadata": { + "SettingsResponse": { "properties": { - "name": { - "type": "string", - "title": "Name", - "description": "Name of the input parameter" + "agent_settings": { + "additionalProperties": true, + "type": "object", + "title": "Agent Settings" }, - "description": { - "type": "string", - "title": "Description", - "description": "Description of the input parameter" + "conversation_settings": { + "additionalProperties": true, + "type": "object", + "title": "Conversation Settings" + }, + "llm_api_key_is_set": { + "type": "boolean", + "title": "Llm Api Key Is Set" } }, "type": "object", - "required": [ - "name", - "description" - ], - "title": "InputMetadata", - "description": "Metadata for task skill inputs." + "required": ["agent_settings", "conversation_settings", "llm_api_key_is_set"], + "title": "SettingsResponse", + "description": "Response model for GET /api/settings.\n\nContains the full settings payload including agent configuration,\nconversation settings, and a flag indicating if an LLM API key is set.\n\nThe ``agent_settings`` and ``conversation_settings`` fields are raw dicts\nbecause the server controls secret serialization via context. Use the\ntyped accessor methods for validation:\n\nExample::\n\n response = SettingsResponse.model_validate(api_response.json())\n agent = response.get_agent_settings() # Returns AgentSettingsConfig\n conv = response.get_conversation_settings() # Returns ConversationSettings" }, - "KeywordTrigger": { + "SettingsSchema": { "properties": { - "type": { + "model_name": { "type": "string", - "const": "keyword", - "title": "Type", - "default": "keyword" + "title": "Model Name" }, - "keywords": { + "sections": { "items": { - "type": "string" + "$ref": "#/components/schemas/SettingsSectionSchema" }, "type": "array", - "title": "Keywords" + "title": "Sections" } }, "type": "object", - "required": [ - "keywords" - ], - "title": "KeywordTrigger", - "description": "Trigger for keyword-based skills.\n\nThese skills are activated when specific keywords appear in the user's query." + "required": ["model_name", "sections"], + "title": "SettingsSchema" }, - "LLM": { + "SettingsSectionSchema": { "properties": { - "model": { - "type": "string", - "title": "Model", - "description": "Model name.", - "default": "claude-sonnet-4-20250514" - }, - "api_key": { - "anyOf": [ - { - "type": "string", - "format": "password", - "writeOnly": true - }, - { - "type": "null" - } - ], - "title": "Api Key", - "description": "API key." - }, - "base_url": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Base Url", - "description": "Custom base URL." - }, - "api_version": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "title": "Api Version", - "description": "API version (e.g., Azure)." + "key": { + "type": "string", + "title": "Key" }, - "aws_access_key_id": { + "label": { + "type": "string", + "title": "Label" + }, + "fields": { + "items": { + "$ref": "#/components/schemas/SettingsFieldSchema" + }, + "type": "array", + "title": "Fields" + }, + "variant": { "anyOf": [ { - "type": "string", - "format": "password", - "writeOnly": true + "type": "string" }, { "type": "null" } ], - "title": "Aws Access Key Id" - }, - "aws_secret_access_key": { + "title": "Variant", + "description": "When set, this section only applies to the named ``AgentSettings`` variant (e.g. ``'openhands'`` or ``'acp'``). The GUI filters sections by the current ``agent_kind`` value; sections with ``variant=None`` are always shown." + } + }, + "type": "object", + "required": ["key", "label", "fields"], + "title": "SettingsSectionSchema" + }, + "SettingsUpdateRequest": { + "properties": { + "agent_settings_diff": { "anyOf": [ { - "type": "string", - "format": "password", - "writeOnly": true + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Aws Secret Access Key" + "title": "Agent Settings Diff" }, - "aws_region_name": { + "conversation_settings_diff": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Aws Region Name" - }, - "openrouter_site_url": { + "title": "Conversation Settings Diff" + } + }, + "type": "object", + "title": "SettingsUpdateRequest", + "description": "Request model for PATCH /api/settings.\n\nSupports partial updates via diff objects that are deep-merged with\nexisting settings." + }, + "Skill": { + "properties": { + "name": { "type": "string", - "title": "Openrouter Site Url", - "default": "https://docs.all-hands.dev/" + "title": "Name" }, - "openrouter_app_name": { + "content": { "type": "string", - "title": "Openrouter App Name", - "default": "OpenHands" - }, - "num_retries": { - "type": "integer", - "minimum": 0.0, - "title": "Num Retries", - "default": 5 - }, - "retry_multiplier": { - "type": "number", - "minimum": 0.0, - "title": "Retry Multiplier", - "default": 8.0 - }, - "retry_min_wait": { - "type": "integer", - "minimum": 0.0, - "title": "Retry Min Wait", - "default": 8 - }, - "retry_max_wait": { - "type": "integer", - "minimum": 0.0, - "title": "Retry Max Wait", - "default": 64 + "title": "Content" }, - "timeout": { + "trigger": { "anyOf": [ { - "type": "integer", - "minimum": 0.0 + "oneOf": [ + { + "$ref": "#/components/schemas/KeywordTrigger" + }, + { + "$ref": "#/components/schemas/TaskTrigger" + } + ], + "discriminator": { + "propertyName": "type", + "mapping": { + "keyword": "#/components/schemas/KeywordTrigger", + "task": "#/components/schemas/TaskTrigger" + } + } }, { "type": "null" } ], - "title": "Timeout", - "description": "HTTP timeout (s)." - }, - "max_message_chars": { - "type": "integer", - "minimum": 1.0, - "title": "Max Message Chars", - "description": "Approx max chars in each event/content sent to the LLM.", - "default": 30000 + "title": "Trigger", + "description": "Trigger determines when skill content is auto-injected. None = no auto-injection (for AgentSkills: agent reads on demand; for legacy: full content always in system prompt). KeywordTrigger = auto-inject when keywords appear in user messages. TaskTrigger = auto-inject for specific tasks, may require user input." }, - "temperature": { + "source": { "anyOf": [ { - "type": "number", - "minimum": 0.0 + "type": "string" }, { "type": "null" } ], - "title": "Temperature", - "default": 0.0 + "title": "Source", + "description": "The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill." }, - "top_p": { + "mcp_tools": { "anyOf": [ { - "type": "number", - "maximum": 1.0, - "minimum": 0.0 + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Top P", - "default": 1.0 + "title": "Mcp Tools", + "description": "MCP tools configuration for the skill (repo skills only). It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format" }, - "top_k": { - "anyOf": [ - { - "type": "number", - "minimum": 0.0 - }, - { - "type": "null" - } - ], - "title": "Top K" + "inputs": { + "items": { + "$ref": "#/components/schemas/InputMetadata" + }, + "type": "array", + "title": "Inputs", + "description": "Input metadata for the skill (task skills only)" }, - "custom_llm_provider": { + "is_agentskills_format": { + "type": "boolean", + "title": "Is Agentskills Format", + "description": "Whether this skill was loaded from a SKILL.md file following the AgentSkills standard. AgentSkills-format skills use progressive disclosure: always listed in with name, description, and location. If the skill also has triggers, content is auto-injected when triggered AND agent can read file anytime.", + "default": false + }, + "version": { + "type": "string", + "title": "Version", + "description": "Skill version (AgentSkills standard field).", + "default": "1.0.0" + }, + "description": { "anyOf": [ { "type": "string" @@ -4066,126 +15344,210 @@ "type": "null" } ], - "title": "Custom Llm Provider" + "title": "Description", + "description": "A brief description of what the skill does and when to use it. Descriptions exceeding MAX_DESCRIPTION_LENGTH are truncated with a notice pointing to the skill's source path." }, - "max_input_tokens": { + "license": { "anyOf": [ { - "type": "integer", - "minimum": 1.0 + "type": "string" }, { "type": "null" } ], - "title": "Max Input Tokens", - "description": "The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4)." + "title": "License", + "description": "The license under which the skill is distributed. AgentSkills standard field (e.g., 'Apache-2.0', 'MIT')." }, - "max_output_tokens": { + "compatibility": { "anyOf": [ { - "type": "integer", - "minimum": 1.0 + "type": "string" }, { "type": "null" } ], - "title": "Max Output Tokens", - "description": "The maximum number of output tokens. This is sent to the LLM." + "title": "Compatibility", + "description": "Environment requirements or compatibility notes for the skill. AgentSkills standard field (e.g., 'Requires git and docker')." }, - "input_cost_per_token": { + "metadata": { "anyOf": [ { - "type": "number", - "minimum": 0.0 + "additionalProperties": { + "type": "string" + }, + "type": "object" }, { "type": "null" } ], - "title": "Input Cost Per Token", - "description": "The cost per input token. This will available in logs for user." + "title": "Metadata", + "description": "Arbitrary key-value metadata for the skill. AgentSkills standard field for extensibility." }, - "output_cost_per_token": { + "allowed_tools": { "anyOf": [ { - "type": "number", - "minimum": 0.0 + "items": { + "type": "string" + }, + "type": "array" }, { "type": "null" } ], - "title": "Output Cost Per Token", - "description": "The cost per output token. This will available in logs for user." + "title": "Allowed Tools", + "description": "List of pre-approved tools for this skill. AgentSkills standard field (parsed from space-delimited string)." }, - "ollama_base_url": { + "disable_model_invocation": { + "type": "boolean", + "title": "Disable Model Invocation", + "description": "Whether this skill can only be activated by trigger matching and should not be advertised to the model for direct invocation.", + "default": false + }, + "resources": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/SkillResources" }, { "type": "null" } ], - "title": "Ollama Base Url" + "description": "Resource directories for the skill (scripts/, references/, assets/). AgentSkills standard field. Only populated for SKILL.md directory format." + } + }, + "type": "object", + "required": ["name", "content"], + "title": "Skill", + "description": "A skill provides specialized knowledge or functionality.\n\nSkill behavior depends on format (is_agentskills_format) and trigger:\n\nAgentSkills format (SKILL.md files):\n- Always listed in with name, description, location\n- Agent reads full content on demand (progressive disclosure)\n- If has triggers: content is ALSO auto-injected when triggered\n\nLegacy OpenHands format:\n- With triggers: Listed in , content injected on trigger\n- Without triggers (None): Full content in , always active\n\nThis model supports both OpenHands-specific fields and AgentSkills standard\nfields (https://agentskills.io/specification) for cross-platform compatibility." + }, + "SkillInfo": { + "properties": { + "name": { + "type": "string", + "title": "Name" }, - "drop_params": { - "type": "boolean", - "title": "Drop Params", - "default": true + "type": { + "type": "string", + "enum": ["repo", "knowledge", "agentskills"], + "title": "Type" }, - "modify_params": { - "type": "boolean", - "title": "Modify Params", - "description": "Modify params allows litellm to do transformations like adding a default message, when a message is empty.", - "default": true + "content": { + "type": "string", + "title": "Content" }, - "disable_vision": { + "triggers": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Triggers" + }, + "source": { "anyOf": [ { - "type": "boolean" + "type": "string" }, { "type": "null" } ], - "title": "Disable Vision", - "description": "If model is vision capable, this option allows to disable image processing (useful for cost reduction)." + "title": "Source" }, - "disable_stop_word": { + "description": { "anyOf": [ { - "type": "boolean" + "type": "string" }, { "type": "null" } ], - "title": "Disable Stop Word", - "description": "Disable using of stop word.", + "title": "Description" + }, + "is_agentskills_format": { + "type": "boolean", + "title": "Is Agentskills Format", + "default": false + }, + "disable_model_invocation": { + "type": "boolean", + "title": "Disable Model Invocation", "default": false + } + }, + "type": "object", + "required": ["name", "type", "content"], + "title": "SkillInfo", + "description": "Skill information returned by the API." + }, + "SkillResources": { + "properties": { + "skill_root": { + "type": "string", + "title": "Skill Root", + "description": "Root directory of the skill (absolute path)" + }, + "scripts": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Scripts", + "description": "List of script files in scripts/ directory (relative paths)" + }, + "references": { + "items": { + "type": "string" + }, + "type": "array", + "title": "References", + "description": "List of reference files in references/ directory (relative paths)" + }, + "assets": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Assets", + "description": "List of asset files in assets/ directory (relative paths)" + } + }, + "type": "object", + "required": ["skill_root"], + "title": "SkillResources", + "description": "Resource directories for a skill (AgentSkills standard).\n\nPer the AgentSkills specification, skills can include:\n- scripts/: Executable scripts the agent can run\n- references/: Reference documentation and examples\n- assets/: Static assets (images, data files, etc.)" + }, + "SkillsRequest": { + "properties": { + "load_public": { + "type": "boolean", + "title": "Load Public", + "description": "Load public skills from OpenHands/extensions repo", + "default": true }, - "caching_prompt": { + "load_user": { "type": "boolean", - "title": "Caching Prompt", - "description": "Enable caching of prompts.", + "title": "Load User", + "description": "Load user skills from ~/.openhands/skills/", "default": true }, - "log_completions": { + "load_project": { "type": "boolean", - "title": "Log Completions", - "description": "Enable logging of completions.", - "default": false + "title": "Load Project", + "description": "Load project skills from workspace", + "default": true }, - "log_completions_folder": { - "type": "string", - "title": "Log Completions Folder", - "description": "The folder to log LLM completions to. Required if log_completions is True.", - "default": "logs/completions" + "load_org": { + "type": "boolean", + "title": "Load Org", + "description": "Load organization-level skills", + "default": true }, - "custom_tokenizer": { + "marketplace_path": { "anyOf": [ { "type": "string" @@ -4194,317 +15556,174 @@ "type": "null" } ], - "title": "Custom Tokenizer", - "description": "A custom tokenizer to use for token counting." + "title": "Marketplace Path", + "description": "Relative marketplace JSON path for public skills. Set to null to load all public skills.", + "default": "marketplaces/default.json" }, - "native_tool_calling": { + "project_dir": { "anyOf": [ { - "type": "boolean" + "type": "string" }, { "type": "null" } ], - "title": "Native Tool Calling", - "description": "Whether to use native tool calling if supported by the model. Can be True, False, or not set." + "title": "Project Dir", + "description": "Workspace directory path for project skills" }, - "reasoning_effort": { + "org_config": { "anyOf": [ { - "type": "string", - "enum": [ - "low", - "medium", - "high", - "none" - ] + "$ref": "#/components/schemas/OrgConfig" }, { "type": "null" } ], - "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." - }, - "enable_encrypted_reasoning": { - "type": "boolean", - "title": "Enable Encrypted Reasoning", - "description": "If True, ask for ['reasoning.encrypted_content'] in Responses API include.", - "default": false + "description": "Organization skills configuration" }, - "extended_thinking_budget": { + "sandbox_config": { "anyOf": [ { - "type": "integer" + "$ref": "#/components/schemas/SandboxConfig" }, { "type": "null" } ], - "title": "Extended Thinking Budget", - "description": "The budget tokens for extended thinking, supported by Anthropic models.", - "default": 200000 + "description": "Sandbox skills configuration" + } + }, + "type": "object", + "title": "SkillsRequest", + "description": "Request body for loading skills." + }, + "SkillsResponse": { + "properties": { + "skills": { + "items": { + "$ref": "#/components/schemas/SkillInfo" + }, + "type": "array", + "title": "Skills" }, - "seed": { + "sources": { + "additionalProperties": { + "type": "integer" + }, + "type": "object", + "title": "Sources", + "description": "Count of skills loaded from each source" + } + }, + "type": "object", + "required": ["skills"], + "title": "SkillsResponse", + "description": "Response containing all available skills." + }, + "StartACPConversationRequest": { + "properties": { + "workspace": { + "$ref": "#/components/schemas/LocalWorkspace-Input", + "description": "Working directory for agent operations and tool execution." + }, + "worktree": { + "type": "boolean", + "title": "Worktree", + "description": "If true and the workspace is already inside a git repository, create a dedicated git worktree for this conversation under `/tmp/conversation-worktrees//`.", + "default": false + }, + "conversation_id": { "anyOf": [ { - "type": "integer" + "type": "string", + "format": "uuid" }, { "type": "null" } ], - "title": "Seed", - "description": "The seed to use for random number generation." + "title": "Conversation Id", + "description": "Optional conversation ID. If not provided, a random UUID will be generated." }, - "safety_settings": { + "confirmation_policy": { + "$ref": "#/components/schemas/ConfirmationPolicyBase-Input", + "description": "Controls when the conversation will prompt the user before continuing. Defaults to never.", + "default": { + "kind": "NeverConfirm" + } + }, + "security_analyzer": { "anyOf": [ { - "items": { - "additionalProperties": { - "type": "string" - }, - "type": "object" - }, - "type": "array" + "$ref": "#/components/schemas/SecurityAnalyzerBase-Input" }, { "type": "null" } ], - "title": "Safety Settings", - "description": "Safety settings for models that support them (like Mistral AI and Gemini)" - }, - "usage_id": { - "type": "string", - "title": "Usage Id", - "description": "Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.", - "default": "default" - }, - "metadata": { - "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'}" - }, - "OVERRIDE_ON_SERIALIZE": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Override On Serialize", - "default": [ - "api_key", - "aws_access_key_id", - "aws_secret_access_key" - ] - } - }, - "additionalProperties": false, - "type": "object", - "title": "LLM", - "description": "Refactored LLM: simple `completion()`, centralized Telemetry, tiny helpers." - }, - "LLMSummarizingCondenser": { - "properties": { - "kind": { - "type": "string", - "const": "LLMSummarizingCondenser", - "title": "Kind", - "default": "LLMSummarizingCondenser" - }, - "llm": { - "$ref": "#/components/schemas/LLM" - }, - "max_size": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Max Size", - "default": 120 - }, - "keep_first": { - "type": "integer", - "minimum": 0.0, - "title": "Keep First", - "default": 4 - } - }, - "type": "object", - "required": [ - "llm" - ], - "title": "LLMSummarizingCondenser" - }, - "LocalWorkspace": { - "properties": { - "kind": { - "type": "string", - "const": "LocalWorkspace", - "title": "Kind", - "default": "LocalWorkspace" - }, - "working_dir": { - "type": "string", - "title": "Working Dir", - "description": "The working directory for agent operations and tool execution." - } - }, - "type": "object", - "required": [ - "working_dir" - ], - "title": "LocalWorkspace", - "description": "Mixin providing local workspace operations." - }, - "LookupSecret": { - "properties": { - "kind": { - "type": "string", - "const": "LookupSecret", - "title": "Kind", - "default": "LookupSecret" + "description": "Optional security analyzer to evaluate action risks." }, - "description": { + "initial_message": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/SendMessageRequest" }, { "type": "null" } ], - "title": "Description", - "description": "Optional description for this secret" - }, - "url": { - "type": "string", - "title": "Url" - }, - "headers": { - "additionalProperties": { - "type": "string" - }, - "type": "object", - "title": "Headers" - } - }, - "type": "object", - "required": [ - "url" - ], - "title": "LookupSecret", - "description": "A secret looked up from some external url" - }, - "MCPToolAction": { - "properties": { - "kind": { - "type": "string", - "const": "MCPToolAction", - "title": "Kind", - "default": "MCPToolAction" - }, - "data": { - "additionalProperties": true, - "type": "object", - "title": "Data", - "description": "Dynamic data fields from the tool call" - } - }, - "additionalProperties": false, - "type": "object", - "title": "MCPToolAction", - "description": "Schema for MCP input action.\n\nIt is just a thin wrapper around raw JSON and does\nnot do any validation.\n\nValidation will be performed by MCPTool.__call__\nby constructing dynamically created Pydantic model\nfrom the MCP tool input schema." - }, - "MCPToolObservation": { - "properties": { - "kind": { - "type": "string", - "const": "MCPToolObservation", - "title": "Kind", - "default": "MCPToolObservation" + "description": "Initial message to pass to the LLM" }, - "content": { - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/TextContent" - }, - { - "$ref": "#/components/schemas/ImageContent" - } - ] - }, - "type": "array", - "title": "Content", - "description": "Content returned from the MCP tool converted to LLM Ready TextContent or ImageContent" + "max_iterations": { + "type": "integer", + "minimum": 1.0, + "title": "Max Iterations", + "description": "If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops.", + "default": 500 }, - "is_error": { + "stuck_detection": { "type": "boolean", - "title": "Is Error", - "description": "Whether the call resulted in an error", - "default": false - }, - "tool_name": { - "type": "string", - "title": "Tool Name", - "description": "Name of the tool that was called" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "tool_name" - ], - "title": "MCPToolObservation", - "description": "Observation from MCP tool execution." - }, - "Message": { - "properties": { - "role": { - "type": "string", - "enum": [ - "user", - "system", - "assistant", - "tool" - ], - "title": "Role" - }, - "content": { - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/TextContent" - }, - { - "$ref": "#/components/schemas/ImageContent" - } - ] + "title": "Stuck Detection", + "description": "If true, the conversation will use stuck detection to prevent infinite loops.", + "default": true + }, + "secrets": { + "additionalProperties": { + "$ref": "#/components/schemas/SecretSource-Input" }, - "type": "array", - "title": "Content" + "type": "object", + "title": "Secrets", + "description": "Secrets available in the conversation" }, - "cache_enabled": { + "secrets_encrypted": { "type": "boolean", - "title": "Cache Enabled", + "title": "Secrets Encrypted", + "description": "If true, indicates that secret values in the agent configuration are cipher-encrypted and should be decrypted by the server before use. This enables secure round-tripping of settings through untrusted clients (e.g., frontend) that received encrypted values via the X-Expose-Secrets header. Flow: client calls GET /api/settings with X-Expose-Secrets: encrypted to receive cipher-encrypted secrets, then passes them in the agent config with secrets_encrypted=True so the server can decrypt them.", "default": false }, - "vision_enabled": { - "type": "boolean", - "title": "Vision Enabled", - "default": false + "tool_module_qualnames": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Tool Module Qualnames", + "description": "Mapping of tool names to their module qualnames from the client's registry. These modules will be dynamically imported on the server to register the tools for this conversation." }, - "function_calling_enabled": { - "type": "boolean", - "title": "Function Calling Enabled", - "default": false + "agent_definitions": { + "items": { + "$ref": "#/components/schemas/AgentDefinition" + }, + "type": "array", + "title": "Agent Definitions", + "description": "Agent definitions from the client's registry. These are registered on the server so that DelegateTool and TaskSetTool can see user-registered subagents." }, - "tool_calls": { + "plugins": { "anyOf": [ { "items": { - "$ref": "#/components/schemas/MessageToolCall" + "$ref": "#/components/schemas/PluginSource" }, "type": "array" }, @@ -4512,20 +15731,35 @@ "type": "null" } ], - "title": "Tool Calls" + "title": "Plugins", + "description": "List of plugins to load for this conversation. Plugins are loaded and their skills/MCP config are merged into the agent. Hooks are extracted and stored for runtime execution." }, - "tool_call_id": { + "hook_config": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/HookConfig-Input" }, { "type": "null" } ], - "title": "Tool Call Id" + "description": "Optional hook configuration for this conversation. Hooks are shell scripts that run at key lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, etc.). If both hook_config and plugins are provided, they are merged with explicit hooks running before plugin hooks." }, - "name": { + "tags": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Tags", + "description": "Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters." + }, + "autotitle": { + "type": "boolean", + "title": "Autotitle", + "description": "If true, automatically generate a title for the conversation from the first user message. Precedence: title_llm_profile (if set and loads) → agent.llm → message truncation.", + "default": true + }, + "title_llm_profile": { "anyOf": [ { "type": "string" @@ -4534,423 +15768,473 @@ "type": "null" } ], - "title": "Name" + "title": "Title Llm Profile", + "description": "Optional LLM profile name for title generation. If set, the LLM is loaded from LLMProfileStore (~/.openhands/profiles/) and used for LLM-based title generation. This enables using a fast/cheap model for titles regardless of the agent's main model. If not set (or profile loading fails), title generation falls back to the agent's LLM." }, - "force_string_serializer": { + "agent_settings": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Agent Settings", + "description": "Optional agent settings payload. If `agent` is omitted, this is validated with the AgentSettingsBase `agent_kind` discriminator and used to construct the concrete agent." + }, + "agent": { + "$ref": "#/components/schemas/AgentBase-Input" + } + }, + "type": "object", + "required": ["workspace"], + "title": "StartACPConversationRequest", + "description": "Deprecated compatibility alias for ACP-capable start requests.\n\nUse :class:`StartConversationRequest` instead. It now supports both regular\nOpenHands agents and ACP agents through the same request contract." + }, + "StartConversationRequest": { + "properties": { + "workspace": { + "$ref": "#/components/schemas/LocalWorkspace-Input", + "description": "Working directory for agent operations and tool execution." + }, + "worktree": { "type": "boolean", - "title": "Force String Serializer", + "title": "Worktree", + "description": "If true and the workspace is already inside a git repository, create a dedicated git worktree for this conversation under `/tmp/conversation-worktrees//`.", "default": false }, - "reasoning_content": { + "conversation_id": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "uuid" }, { "type": "null" } ], - "title": "Reasoning Content", - "description": "Intermediate reasoning/thinking content from reasoning models" + "title": "Conversation Id", + "description": "Optional conversation ID. If not provided, a random UUID will be generated." }, - "thinking_blocks": { - "items": { - "anyOf": [ - { - "$ref": "#/components/schemas/ThinkingBlock" - }, - { - "$ref": "#/components/schemas/RedactedThinkingBlock" - } - ] - }, - "type": "array", - "title": "Thinking Blocks", - "description": "Raw Anthropic thinking blocks for extended thinking feature" + "confirmation_policy": { + "$ref": "#/components/schemas/ConfirmationPolicyBase-Input", + "description": "Controls when the conversation will prompt the user before continuing. Defaults to never.", + "default": { + "kind": "NeverConfirm" + } }, - "responses_reasoning_item": { + "security_analyzer": { "anyOf": [ { - "$ref": "#/components/schemas/ReasoningItemModel" + "$ref": "#/components/schemas/SecurityAnalyzerBase-Input" }, { "type": "null" } ], - "description": "OpenAI Responses reasoning item from model output" - } - }, - "type": "object", - "required": [ - "role" - ], - "title": "Message" - }, - "MessageEvent": { - "properties": { - "kind": { - "type": "string", - "const": "MessageEvent", - "title": "Kind", - "default": "MessageEvent" + "description": "Optional security analyzer to evaluate action risks." }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" + "initial_message": { + "anyOf": [ + { + "$ref": "#/components/schemas/SendMessageRequest" + }, + { + "type": "null" + } + ], + "description": "Initial message to pass to the LLM" }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" + "max_iterations": { + "type": "integer", + "minimum": 1.0, + "title": "Max Iterations", + "description": "If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops.", + "default": 500 }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" - ], - "title": "Source" + "stuck_detection": { + "type": "boolean", + "title": "Stuck Detection", + "description": "If true, the conversation will use stuck detection to prevent infinite loops.", + "default": true }, - "llm_message": { - "$ref": "#/components/schemas/Message", - "description": "The exact LLM message for this message event" + "secrets": { + "additionalProperties": { + "$ref": "#/components/schemas/SecretSource-Input" + }, + "type": "object", + "title": "Secrets", + "description": "Secrets available in the conversation" }, - "activated_skills": { - "items": { + "secrets_encrypted": { + "type": "boolean", + "title": "Secrets Encrypted", + "description": "If true, indicates that secret values in the agent configuration are cipher-encrypted and should be decrypted by the server before use. This enables secure round-tripping of settings through untrusted clients (e.g., frontend) that received encrypted values via the X-Expose-Secrets header. Flow: client calls GET /api/settings with X-Expose-Secrets: encrypted to receive cipher-encrypted secrets, then passes them in the agent config with secrets_encrypted=True so the server can decrypt them.", + "default": false + }, + "tool_module_qualnames": { + "additionalProperties": { "type": "string" }, - "type": "array", - "title": "Activated Skills", - "description": "List of activated skill name" + "type": "object", + "title": "Tool Module Qualnames", + "description": "Mapping of tool names to their module qualnames from the client's registry. These modules will be dynamically imported on the server to register the tools for this conversation." }, - "extended_content": { + "agent_definitions": { "items": { - "$ref": "#/components/schemas/TextContent" + "$ref": "#/components/schemas/AgentDefinition" }, "type": "array", - "title": "Extended Content", - "description": "List of content added by agent context" + "title": "Agent Definitions", + "description": "Agent definitions from the client's registry. These are registered on the server so that DelegateTool and TaskSetTool can see user-registered subagents." + }, + "plugins": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/PluginSource" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Plugins", + "description": "List of plugins to load for this conversation. Plugins are loaded and their skills/MCP config are merged into the agent. Hooks are extracted and stored for runtime execution." + }, + "hook_config": { + "anyOf": [ + { + "$ref": "#/components/schemas/HookConfig-Input" + }, + { + "type": "null" + } + ], + "description": "Optional hook configuration for this conversation. Hooks are shell scripts that run at key lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, etc.). If both hook_config and plugins are provided, they are merged with explicit hooks running before plugin hooks." + }, + "tags": { + "additionalProperties": { + "type": "string" + }, + "type": "object", + "title": "Tags", + "description": "Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters." + }, + "autotitle": { + "type": "boolean", + "title": "Autotitle", + "description": "If true, automatically generate a title for the conversation from the first user message. Precedence: title_llm_profile (if set and loads) → agent.llm → message truncation.", + "default": true + }, + "title_llm_profile": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title Llm Profile", + "description": "Optional LLM profile name for title generation. If set, the LLM is loaded from LLMProfileStore (~/.openhands/profiles/) and used for LLM-based title generation. This enables using a fast/cheap model for titles regardless of the agent's main model. If not set (or profile loading fails), title generation falls back to the agent's LLM." + }, + "agent_settings": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Agent Settings", + "description": "Optional agent settings payload. If `agent` is omitted, this is validated with the AgentSettingsBase `agent_kind` discriminator and used to construct the concrete agent." + }, + "agent": { + "$ref": "#/components/schemas/AgentBase-Input" } }, - "additionalProperties": false, "type": "object", - "required": [ - "source", - "llm_message" - ], - "title": "MessageEvent", - "description": "Message from either agent or user.\n\nThis is originally the \"MessageAction\", but it suppose not to be tool call." + "required": ["workspace"], + "title": "StartConversationRequest", + "description": "Payload to create a new conversation.\n\nSupports any concrete :class:`AgentBase` implementation, including regular\nOpenHands agents and ACP agents. Clients may provide either a concrete\n``agent`` payload or an ``agent_settings`` payload; when ``agent_settings``\nis provided without ``agent``, the settings are validated with the\n``agent_kind`` discriminator and converted to the appropriate agent type." }, - "MessageToolCall": { + "StaticSecret-Input": { "properties": { - "id": { - "type": "string", - "title": "Id", - "description": "Canonical tool call id" - }, - "name": { - "type": "string", - "title": "Name", - "description": "Tool/function name" - }, - "arguments": { - "type": "string", - "title": "Arguments", - "description": "JSON string of arguments" + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description", + "description": "Optional description for this secret" }, - "origin": { - "type": "string", - "enum": [ - "completion", - "responses" + "value": { + "anyOf": [ + { + "type": "string", + "format": "password", + "writeOnly": true + }, + { + "type": "null" + } ], - "title": "Origin", - "description": "Originating API family" + "title": "Value" + }, + "kind": { + "type": "string", + "const": "StaticSecret", + "title": "Kind" } }, "type": "object", - "required": [ - "id", - "name", - "arguments", - "origin" - ], - "title": "MessageToolCall", - "description": "Transport-agnostic tool call representation.\n\nOne canonical id is used for linking across actions/observations and\nfor Responses function_call_output call_id." + "title": "StaticSecret", + "description": "A secret stored locally" }, - "Metrics": { + "StaticSecret-Output": { "properties": { - "model_name": { - "type": "string", - "title": "Model Name", - "description": "Name of the model", - "default": "default" - }, - "accumulated_cost": { - "type": "number", - "minimum": 0.0, - "title": "Accumulated Cost", - "description": "Total accumulated cost, must be non-negative", - "default": 0.0 - }, - "max_budget_per_task": { + "description": { "anyOf": [ { - "type": "number" + "type": "string" }, { "type": "null" } ], - "title": "Max Budget Per Task", - "description": "Maximum budget per task" + "title": "Description", + "description": "Optional description for this secret" }, - "accumulated_token_usage": { + "value": { "anyOf": [ { - "$ref": "#/components/schemas/TokenUsage" + "type": "string", + "format": "password", + "writeOnly": true }, { "type": "null" } ], - "description": "Accumulated token usage across all calls" - }, - "costs": { - "items": { - "$ref": "#/components/schemas/Cost" - }, - "type": "array", - "title": "Costs", - "description": "List of individual costs" - }, - "response_latencies": { - "items": { - "$ref": "#/components/schemas/ResponseLatency" - }, - "type": "array", - "title": "Response Latencies", - "description": "List of response latencies" + "title": "Value" }, - "token_usages": { - "items": { - "$ref": "#/components/schemas/TokenUsage" - }, - "type": "array", - "title": "Token Usages", - "description": "List of token usage records" + "kind": { + "type": "string", + "const": "StaticSecret", + "title": "Kind" } }, "type": "object", - "title": "Metrics", - "description": "Metrics class can record various metrics during running and evaluation.\nWe track:\n - accumulated_cost and costs\n - max_budget_per_task (budget limit)\n - A list of ResponseLatency\n - A list of TokenUsage (one per call)." + "required": ["kind"], + "title": "StaticSecret", + "description": "A secret stored locally" }, - "MetricsSnapshot": { + "StreamingDeltaEvent": { "properties": { - "model_name": { + "id": { "type": "string", - "title": "Model Name", - "description": "Name of the model", - "default": "default" + "title": "Id", + "description": "Unique event id (ULID/UUID)" }, - "accumulated_cost": { - "type": "number", - "minimum": 0.0, - "title": "Accumulated Cost", - "description": "Total accumulated cost, must be non-negative", - "default": 0.0 + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" }, - "max_budget_per_task": { + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "agent" + }, + "content": { "anyOf": [ { - "type": "number" + "type": "string" }, { "type": "null" } ], - "title": "Max Budget Per Task", - "description": "Maximum budget per task" + "title": "Content" }, - "accumulated_token_usage": { + "reasoning_content": { "anyOf": [ { - "$ref": "#/components/schemas/TokenUsage" + "type": "string" }, { "type": "null" } ], - "description": "Accumulated token usage across all calls" + "title": "Reasoning Content" + }, + "kind": { + "type": "string", + "const": "StreamingDeltaEvent", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "title": "MetricsSnapshot", - "description": "A snapshot of metrics at a point in time.\n\nDoes not include lists of individual costs, latencies, or token usages." + "required": ["kind"], + "title": "StreamingDeltaEvent", + "description": "Transient LLM token delta for real-time WebSocket delivery.\n\nNot persisted to the conversation event log: these events are published\ndirectly to PubSub, bypassing the callback chain that writes to\nConversationState.events. Clients reconnecting mid-stream will receive\nthe final MessageEvent from history but none of the deltas that produced\nit — deltas are a UX affordance, not part of the durable conversation\nrecord." }, - "NeverConfirm": { + "SubdirectoryEntry": { "properties": { - "kind": { + "name": { "type": "string", - "const": "NeverConfirm", - "title": "Kind", - "default": "NeverConfirm" + "title": "Name" + }, + "path": { + "type": "string", + "title": "Path" } }, "type": "object", - "title": "NeverConfirm" + "required": ["name", "path"], + "title": "SubdirectoryEntry" }, - "NoOpCondenser": { + "SubdirectoryPage": { "properties": { - "kind": { - "type": "string", - "const": "NoOpCondenser", - "title": "Kind", - "default": "NoOpCondenser" + "items": { + "items": { + "$ref": "#/components/schemas/SubdirectoryEntry" + }, + "type": "array", + "title": "Items" + }, + "next_page_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Next Page Id" } }, "type": "object", - "title": "NoOpCondenser", - "description": "Simple condenser that returns a view un-manipulated.\n\nPrimarily intended for testing purposes." + "required": ["items"], + "title": "SubdirectoryPage" }, - "ObservationEvent": { + "Success": { "properties": { - "kind": { - "type": "string", - "const": "ObservationEvent", - "title": "Kind", - "default": "ObservationEvent" - }, - "id": { - "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" - }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" - }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" - ], - "title": "Source", - "default": "environment" - }, - "tool_name": { + "success": { + "type": "boolean", + "title": "Success", + "default": true + } + }, + "type": "object", + "title": "Success" + }, + "SwitchLLMAction": { + "properties": { + "profile_name": { "type": "string", - "title": "Tool Name", - "description": "The tool name that this observation is responding to" + "title": "Profile Name", + "description": "Name of the saved LLM profile to use for future agent steps." }, - "tool_call_id": { + "reason": { "type": "string", - "title": "Tool Call Id", - "description": "The tool call id that this observation is responding to" - }, - "observation": { - "$ref": "#/components/schemas/Observation" + "title": "Reason", + "description": "Brief reason why this profile is a better fit for the next step." }, - "action_id": { + "kind": { "type": "string", - "title": "Action Id", - "description": "The action id that this observation is responding to" + "const": "SwitchLLMAction", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "tool_name", - "tool_call_id", - "observation", - "action_id" - ], - "title": "ObservationEvent" + "required": ["profile_name", "reason", "kind"], + "title": "SwitchLLMAction", + "description": "Action for switching this conversation to a saved LLM profile." }, - "PauseEvent": { + "SwitchLLMActionWithRisk": { "properties": { - "kind": { + "profile_name": { "type": "string", - "const": "PauseEvent", - "title": "Kind", - "default": "PauseEvent" + "title": "Profile Name", + "description": "Name of the saved LLM profile to use for future agent steps." }, - "id": { + "reason": { "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" + "title": "Reason", + "description": "Brief reason why this profile is a better fit for the next step." }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" }, - "source": { + "kind": { "type": "string", - "enum": [ - "agent", - "user", - "environment" - ], - "title": "Source", - "default": "user" + "const": "SwitchLLMActionWithRisk", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "title": "PauseEvent", - "description": "Event indicating that the agent execution was paused by user request." + "required": ["profile_name", "reason", "kind"], + "title": "SwitchLLMActionWithRisk" }, - "PipelineCondenser-Output": { + "SwitchLLMObservation": { "properties": { - "kind": { - "type": "string", - "const": "PipelineCondenser", - "title": "Kind", - "default": "PipelineCondenser" - }, - "condensers": { + "content": { "items": { - "oneOf": [ - { - "$ref": "#/components/schemas/LLMSummarizingCondenser" - }, + "anyOf": [ { - "$ref": "#/components/schemas/NoOpCondenser" + "$ref": "#/components/schemas/TextContent" }, { - "$ref": "#/components/schemas/PipelineCondenser-Output" - } - ], - "title": "CondenserBase", - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Output__1": "#/components/schemas/LLMSummarizingCondenser", - "openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Output__1": "#/components/schemas/NoOpCondenser", - "openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Output__1": "#/components/schemas/PipelineCondenser-Output" + "$ref": "#/components/schemas/ImageContent" } - } + ] }, "type": "array", - "title": "Condensers" - } - }, - "type": "object", - "required": [ - "condensers" - ], - "title": "PipelineCondenser", - "description": "A condenser that applies a sequence of condensers in order.\n\nAll condensers are defined primarily by their `condense` method, which takes a\n`View` and returns either a new `View` or a `Condensation` event. That means we can\nchain multiple condensers together by passing `View`s along and exiting early if any\ncondenser returns a `Condensation`.\n\nFor example:\n\n # Use the pipeline condenser to chain multiple other condensers together\n condenser = PipelineCondenser(condensers=[\n CondenserA(...),\n CondenserB(...),\n CondenserC(...),\n ])\n\n result = condenser.condense(view)\n\n # Doing the same thing without the pipeline condenser requires more boilerplate\n # for the monadic chaining\n other_result = view\n\n if isinstance(other_result, View):\n other_result = CondenserA(...).condense(other_result)\n\n if isinstance(other_result, View):\n other_result = CondenserB(...).condense(other_result)\n\n if isinstance(other_result, View):\n other_result = CondenserC(...).condense(other_result)\n\n assert result == other_result" - }, - "ReasoningItemModel": { - "properties": { - "id": { + "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 + }, + "profile_name": { + "type": "string", + "title": "Profile Name", + "description": "Name of the profile that the tool attempted to activate." + }, + "reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Reason", + "description": "Reason the agent gave for attempting this LLM profile switch." + }, + "active_model": { "anyOf": [ { "type": "string" @@ -4959,207 +16243,279 @@ "type": "null" } ], - "title": "Id" + "title": "Active Model", + "description": "Model configured by the activated profile, when available." }, - "summary": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Summary" + "kind": { + "type": "string", + "const": "SwitchLLMObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["profile_name", "kind"], + "title": "SwitchLLMObservation", + "description": "Observation returned after switching this conversation's LLM profile." + }, + "SwitchLLMTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" }, - "content": { + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { "anyOf": [ { - "items": { - "type": "string" - }, - "type": "array" + "type": "string" }, { "type": "null" } ], - "title": "Content" + "title": "Observation Type" }, - "encrypted_content": { + "annotations": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" }, { "type": "null" } - ], - "title": "Encrypted Content" + ] }, - "status": { + "meta": { "anyOf": [ { - "type": "string" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "title": "Status" + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "SwitchLLMTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true } }, "type": "object", - "title": "ReasoningItemModel", - "description": "OpenAI Responses reasoning item (non-stream, subset we consume).\n\nDo not log or render encrypted_content." + "required": ["description", "action_type", "kind", "title"], + "title": "SwitchLLMTool", + "description": "Tool for switching a conversation to a saved LLM profile." }, - "RedactedThinkingBlock": { + "SyncResponse": { "properties": { - "type": { + "status": { "type": "string", - "const": "redacted_thinking", - "title": "Type", - "default": "redacted_thinking" + "enum": ["success", "error"], + "title": "Status" }, - "data": { + "message": { "type": "string", - "title": "Data", - "description": "The redacted thinking content" + "title": "Message" } }, "type": "object", - "required": [ - "data" - ], - "title": "RedactedThinkingBlock", - "description": "Redacted thinking block for previous responses without extended thinking.\n\nThis is used as a placeholder for assistant messages that were generated\nbefore extended thinking was enabled." + "required": ["status", "message"], + "title": "SyncResponse", + "description": "Response from skill sync operation." }, - "RemoteWorkspace": { + "SystemPromptEvent": { "properties": { - "kind": { + "id": { "type": "string", - "const": "RemoteWorkspace", - "title": "Kind", - "default": "RemoteWorkspace" + "title": "Id", + "description": "Unique event id (ULID/UUID)" }, - "working_dir": { + "timestamp": { "type": "string", - "title": "Working Dir", - "description": "The working directory for agent operations and tool execution." + "title": "Timestamp", + "description": "Event timestamp" }, - "host": { + "source": { "type": "string", - "title": "Host", - "description": "The remote host URL for the workspace." + "enum": ["agent", "user", "environment", "hook"], + "title": "Source", + "default": "agent" }, - "api_key": { + "system_prompt": { + "$ref": "#/components/schemas/TextContent", + "description": "The system prompt text" + }, + "tools": { + "items": { + "$ref": "#/components/schemas/ToolDefinition" + }, + "type": "array", + "title": "Tools", + "description": "List of tools as ToolDefinition objects" + }, + "dynamic_context": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/TextContent" }, { "type": "null" } ], - "title": "Api Key", - "description": "API key for authenticating with the remote host." + "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)." + }, + "kind": { + "type": "string", + "const": "SystemPromptEvent", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "working_dir", - "host" - ], - "title": "RemoteWorkspace", - "description": "Remote Workspace Implementation." + "required": ["system_prompt", "tools", "kind"], + "title": "SystemPromptEvent", + "description": "System prompt added by the agent.\n\nThe system prompt can optionally include dynamic context that varies between\nconversations. When ``dynamic_context`` is provided, it is included as a\nsecond content block in the same system message. Cache markers are NOT\napplied here - they are applied by ``LLM._apply_prompt_caching()`` when\ncaching is enabled, ensuring provider-specific cache control is only added\nwhen appropriate.\n\nAttributes:\n system_prompt: The static system prompt text (cacheable across conversations)\n tools: List of available tools\n dynamic_context: Optional per-conversation context (hosts, repo info, etc.)\n Sent as a second TextContent block inside the system message." }, - "ResponseLatency": { + "TaskAction": { "properties": { - "model": { + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description", + "description": "A short (3-5 word) description of the task." + }, + "prompt": { "type": "string", - "title": "Model" + "title": "Prompt", + "description": "The task for the agent to perform." }, - "latency": { - "type": "number", - "minimum": 0.0, - "title": "Latency", - "description": "Latency must be non-negative" + "subagent_type": { + "type": "string", + "title": "Subagent Type", + "description": "The type of specialized agent to use for this task.", + "default": "general-purpose" }, - "response_id": { + "resume": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Resume", + "description": "Task ID of the task to resume from." + }, + "kind": { "type": "string", - "title": "Response Id" + "const": "TaskAction", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "model", - "latency", - "response_id" - ], - "title": "ResponseLatency", - "description": "Metric tracking the round-trip time per completion call." + "required": ["prompt", "kind"], + "title": "TaskAction", + "description": "Schema for launching a sub-agent task." }, - "SecretsManager-Output": { + "TaskActionWithRisk": { "properties": { - "secret_sources": { - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/components/schemas/LookupSecret" - }, - { - "$ref": "#/components/schemas/StaticSecret" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__conversation__secret_source__LookupSecret-Output__1": "#/components/schemas/LookupSecret", - "openhands__sdk__conversation__secret_source__StaticSecret-Output__1": "#/components/schemas/StaticSecret" - } + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" } - }, - "type": "object", - "title": "Secret Sources" + ], + "title": "Description", + "description": "A short (3-5 word) description of the task." + }, + "prompt": { + "type": "string", + "title": "Prompt", + "description": "The task for the agent to perform." + }, + "subagent_type": { + "type": "string", + "title": "Subagent Type", + "description": "The type of specialized agent to use for this task.", + "default": "general-purpose" + }, + "resume": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Resume", + "description": "Task ID of the task to resume from." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "TaskActionWithRisk", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "title": "SecretsManager", - "description": "Manages secrets and injects them into bash commands when needed.\n\nThe secrets manager stores a mapping of secret keys to SecretSources\nthat retrieve the actual secret values. When a bash command is about to be\nexecuted, it scans the command for any secret keys and injects the corresponding\nenvironment variables.\n\nSecret sources will redact / encrypt their sensitive values as appropriate when\nserializing, depending on the content of the context. If a context is present\nand contains a 'cipher' object, this is used for encryption. If it contains a\nboolean 'expose_secrets' flag set to True, secrets are dunped in plain text.\nOtherwise secrets are redacted.\n\nAdditionally, it tracks the latest exported values to enable consistent masking\neven when callable secrets fail on subsequent calls." + "required": ["prompt", "kind"], + "title": "TaskActionWithRisk" }, - "SecurityAnalyzerBase": { + "TaskItem": { "properties": { - "kind": { + "title": { "type": "string", - "const": "LLMSecurityAnalyzer", - "title": "Kind", - "default": "LLMSecurityAnalyzer" + "title": "Title", + "description": "A brief title for the task." + }, + "notes": { + "type": "string", + "title": "Notes", + "description": "Additional details or notes about the task.", + "default": "" + }, + "status": { + "type": "string", + "enum": ["todo", "in_progress", "done"], + "title": "Status", + "description": "The current status of the task. One of 'todo', 'in_progress', or 'done'.", + "default": "todo" } }, "type": "object", - "title": "LLMSecurityAnalyzer", - "description": "LLM-based security analyzer.\n\nThis analyzer respects the security_risk attribute that can be set by the LLM\nwhen generating actions, similar to OpenHands' LLMRiskAnalyzer.\n\nIt provides a lightweight security analysis approach that leverages the LLM's\nunderstanding of action context and potential risks." - }, - "SecurityRisk": { - "type": "string", - "enum": [ - "UNKNOWN", - "LOW", - "MEDIUM", - "HIGH" - ], - "title": "SecurityRisk", - "description": "Security risk levels for actions.\n\nBased on OpenHands security risk levels but adapted for agent-sdk.\nInteger values allow for easy comparison and ordering." + "required": ["title"], + "title": "TaskItem" }, - "SendMessageRequest": { + "TaskObservation": { "properties": { - "role": { - "type": "string", - "enum": [ - "user", - "system", - "assistant", - "tool" - ], - "title": "Role", - "default": "user" - }, "content": { "items": { "anyOf": [ @@ -5172,138 +16528,133 @@ ] }, "type": "array", - "title": "Content" + "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." }, - "run": { + "is_error": { "type": "boolean", - "title": "Run", - "description": "Whether the agent loop should automatically run if not running", + "title": "Is Error", + "description": "Whether the observation indicates an error", "default": false - } - }, - "type": "object", - "title": "SendMessageRequest", - "description": "Payload to send a message to the agent.\n\nThis is a simplified version of openhands.sdk.Message." - }, - "ServerInfo": { - "properties": { - "uptime": { - "type": "number", - "title": "Uptime" }, - "idle_time": { - "type": "number", - "title": "Idle Time" - }, - "title": { + "task_id": { "type": "string", - "title": "Title", - "default": "OpenHands Agent Server" + "title": "Task Id", + "description": "The unique identifier of the task." }, - "version": { + "subagent": { "type": "string", - "title": "Version", - "default": "1.0.0a4" + "title": "Subagent", + "description": "The subagent of the task." }, - "docs": { + "status": { "type": "string", - "title": "Docs", - "default": "/docs" + "title": "Status", + "description": "The status of the task." }, - "redoc": { + "kind": { "type": "string", - "title": "Redoc", - "default": "/redoc" + "const": "TaskObservation", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "uptime", - "idle_time" - ], - "title": "ServerInfo" + "required": ["task_id", "subagent", "status", "kind"], + "title": "TaskObservation", + "description": "Observation from a task execution." }, - "SetConfirmationPolicyRequest": { + "TaskTool": { "properties": { - "policy": { - "oneOf": [ + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ { - "$ref": "#/components/schemas/AlwaysConfirm" + "type": "string" }, { - "$ref": "#/components/schemas/ConfirmRisky" + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" }, { - "$ref": "#/components/schemas/NeverConfirm" + "type": "null" } - ], - "title": "ConfirmationPolicyBase", - "description": "The confirmation policy to set", - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__security__confirmation_policy__AlwaysConfirm-Input__1": "#/components/schemas/AlwaysConfirm", - "openhands__sdk__security__confirmation_policy__ConfirmRisky-Input__1": "#/components/schemas/ConfirmRisky", - "openhands__sdk__security__confirmation_policy__NeverConfirm-Input__1": "#/components/schemas/NeverConfirm" + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" } - } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "TaskTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true } }, "type": "object", - "required": [ - "policy" - ], - "title": "SetConfirmationPolicyRequest", - "description": "Payload to set confirmation policy for a conversation." + "required": ["description", "action_type", "kind", "title"], + "title": "TaskTool", + "description": "Tool for launching (blocking) sub-agent tasks." }, - "Skill": { + "TaskToolSet": { "properties": { - "name": { + "description": { "type": "string", - "title": "Name" + "title": "Description" }, - "content": { + "action_type": { "type": "string", - "title": "Content" + "title": "Action Type" }, - "trigger": { + "observation_type": { "anyOf": [ { - "oneOf": [ - { - "$ref": "#/components/schemas/KeywordTrigger" - }, - { - "$ref": "#/components/schemas/TaskTrigger" - } - ], - "discriminator": { - "propertyName": "type", - "mapping": { - "keyword": "#/components/schemas/KeywordTrigger", - "task": "#/components/schemas/TaskTrigger" - } - } + "type": "string" }, { "type": "null" } ], - "title": "Trigger" + "title": "Observation Type" }, - "source": { + "annotations": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" }, { "type": "null" } - ], - "title": "Source", - "description": "The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill." + ] }, - "mcp_tools": { + "meta": { "anyOf": [ { "additionalProperties": true, @@ -5313,344 +16664,446 @@ "type": "null" } ], - "title": "Mcp Tools", - "description": "MCP tools configuration for the skill (repo skills only). It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format" + "title": "Meta" }, - "inputs": { + "kind": { + "type": "string", + "const": "TaskToolSet", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "TaskToolSet", + "description": "Task tool set.\n\nCreates the Task tool backed by a shared TaskManager.\n\nUsage:\n from openhands.tools.task import TaskToolSet\n\n agent = Agent(\n llm=llm,\n tools=[\n Tool(name=TerminalTool.name),\n Tool(name=FileEditorTool.name),\n Tool(name=TaskToolSet.name),\n ],\n )" + }, + "TaskTrackerAction": { + "properties": { + "command": { + "type": "string", + "enum": ["view", "plan"], + "title": "Command", + "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.", + "default": "view" + }, + "task_list": { "items": { - "$ref": "#/components/schemas/InputMetadata" + "$ref": "#/components/schemas/TaskItem" }, "type": "array", - "title": "Inputs", - "description": "Input metadata for the skill (task skills only)" + "title": "Task List", + "description": "The full task list. Required parameter of `plan` command." + }, + "kind": { + "type": "string", + "const": "TaskTrackerAction", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "name", - "content", - "trigger" - ], - "title": "Skill", - "description": "A skill provides specialized knowledge or functionality.\n\nSkills use triggers to determine when they should be activated:\n- None: Always active, for repository-specific guidelines\n- KeywordTrigger: Activated when keywords appear in user messages\n- TaskTrigger: Activated for specific tasks, may require user input" + "required": ["kind"], + "title": "TaskTrackerAction", + "description": "An action where the agent writes or updates a task list for task management." }, - "StartConversationRequest": { + "TaskTrackerActionWithRisk": { "properties": { - "agent": { - "$ref": "#/components/schemas/Agent-Output" + "command": { + "type": "string", + "enum": ["view", "plan"], + "title": "Command", + "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.", + "default": "view" }, - "workspace": { - "$ref": "#/components/schemas/LocalWorkspace", - "description": "Working directory for agent operations and tool execution" + "task_list": { + "items": { + "$ref": "#/components/schemas/TaskItem" + }, + "type": "array", + "title": "Task List", + "description": "The full task list. Required parameter of `plan` command." }, - "conversation_id": { + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "TaskTrackerActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "TaskTrackerActionWithRisk" + }, + "TaskTrackerObservation": { + "properties": { + "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": ["view", "plan"], + "title": "Command", + "description": "The command that was executed: \"view\" or \"plan\"." + }, + "task_list": { + "items": { + "$ref": "#/components/schemas/TaskItem" + }, + "type": "array", + "title": "Task List", + "description": "The current task list" + }, + "kind": { + "type": "string", + "const": "TaskTrackerObservation", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["command", "kind"], + "title": "TaskTrackerObservation", + "description": "This data class represents the result of a task tracking operation." + }, + "TaskTrackerTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { "anyOf": [ { - "type": "string", - "format": "uuid" + "type": "string" }, { "type": "null" } ], - "title": "Conversation Id", - "description": "Optional conversation ID. If not provided, a random UUID will be generated." + "title": "Observation Type" }, - "confirmation_policy": { - "oneOf": [ - { - "$ref": "#/components/schemas/AlwaysConfirm" - }, + "annotations": { + "anyOf": [ { - "$ref": "#/components/schemas/ConfirmRisky" + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" }, { - "$ref": "#/components/schemas/NeverConfirm" - } - ], - "title": "ConfirmationPolicyBase", - "description": "Controls when the conversation will prompt the user before continuing. Defaults to never.", - "default": { - "kind": "NeverConfirm" - }, - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__security__confirmation_policy__AlwaysConfirm-Input__1": "#/components/schemas/AlwaysConfirm", - "openhands__sdk__security__confirmation_policy__ConfirmRisky-Input__1": "#/components/schemas/ConfirmRisky", - "openhands__sdk__security__confirmation_policy__NeverConfirm-Input__1": "#/components/schemas/NeverConfirm" + "type": "null" } - } + ] }, - "initial_message": { + "meta": { "anyOf": [ { - "$ref": "#/components/schemas/SendMessageRequest" + "additionalProperties": true, + "type": "object" }, { "type": "null" } ], - "description": "Initial message to pass to the LLM" + "title": "Meta" }, - "max_iterations": { - "type": "integer", - "minimum": 1.0, - "title": "Max Iterations", - "description": "If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops.", - "default": 500 + "kind": { + "type": "string", + "const": "TaskTrackerTool", + "title": "Kind" }, - "stuck_detection": { - "type": "boolean", - "title": "Stuck Detection", - "description": "If true, the conversation will use stuck detection to prevent infinite loops.", - "default": true + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "TaskTrackerTool", + "description": "A ToolDefinition subclass that automatically initializes a TaskTrackerExecutor." + }, + "TaskTrigger": { + "properties": { + "type": { + "type": "string", + "const": "task", + "title": "Type", + "default": "task" }, - "secrets": { - "additionalProperties": { - "oneOf": [ - { - "$ref": "#/components/schemas/LookupSecret" - }, - { - "$ref": "#/components/schemas/StaticSecret" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__conversation__secret_source__LookupSecret-Input__1": "#/components/schemas/LookupSecret", - "openhands__sdk__conversation__secret_source__StaticSecret-Input__1": "#/components/schemas/StaticSecret" - } - } + "triggers": { + "items": { + "type": "string" }, - "type": "object", - "title": "Secrets", - "description": "Secrets available in the conversation" + "type": "array", + "title": "Triggers" } }, "type": "object", - "required": [ - "agent", - "workspace" - ], - "title": "StartConversationRequest", - "description": "Payload to create a new conversation.\n\nContains an Agent configuration along with conversation-specific options." + "required": ["triggers"], + "title": "TaskTrigger", + "description": "Trigger for task-specific skills.\n\nThese skills are activated for specific task types and can modify prompts." }, - "StaticSecret": { + "TerminalAction": { "properties": { - "kind": { + "command": { "type": "string", - "const": "StaticSecret", - "title": "Kind", - "default": "StaticSecret" + "title": "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." }, - "description": { + "is_input": { + "type": "boolean", + "title": "Is Input", + "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.", + "default": false + }, + "timeout": { "anyOf": [ { - "type": "string" + "type": "number", + "minimum": 0.0 }, { "type": "null" } ], - "title": "Description", - "description": "Optional description for this secret" + "title": "Timeout", + "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)." }, - "value": { - "type": "string", - "format": "password", - "title": "Value", - "writeOnly": true - } - }, - "type": "object", - "required": [ - "value" - ], - "title": "StaticSecret", - "description": "A secret stored locally" - }, - "Success": { - "properties": { - "success": { + "reset": { "type": "boolean", - "title": "Success", - "default": true + "title": "Reset", + "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.", + "default": false + }, + "kind": { + "type": "string", + "const": "TerminalAction", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "title": "Success" + "required": ["command", "kind"], + "title": "TerminalAction", + "description": "Schema for terminal command execution." }, - "SystemPromptEvent": { + "TerminalActionWithRisk": { "properties": { - "kind": { - "type": "string", - "const": "SystemPromptEvent", - "title": "Kind", - "default": "SystemPromptEvent" - }, - "id": { + "command": { "type": "string", - "title": "Id", - "description": "Unique event id (ULID/UUID)" + "title": "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." }, - "timestamp": { - "type": "string", - "title": "Timestamp", - "description": "Event timestamp" + "is_input": { + "type": "boolean", + "title": "Is Input", + "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.", + "default": false }, - "source": { - "type": "string", - "enum": [ - "agent", - "user", - "environment" + "timeout": { + "anyOf": [ + { + "type": "number", + "minimum": 0.0 + }, + { + "type": "null" + } ], - "title": "Source", - "default": "agent" - }, - "system_prompt": { - "$ref": "#/components/schemas/TextContent", - "description": "The system prompt text" + "title": "Timeout", + "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)." }, - "tools": { - "items": { - "$ref": "#/components/schemas/ChatCompletionToolParam" - }, - "type": "array", - "title": "Tools", - "description": "List of tools in OpenAI tool format" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "system_prompt", - "tools" - ], - "title": "SystemPromptEvent", - "description": "System prompt added by the agent." - }, - "TaskItem": { - "properties": { - "title": { - "type": "string", - "title": "Title", - "description": "A brief title for the task." + "reset": { + "type": "boolean", + "title": "Reset", + "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.", + "default": false }, - "notes": { - "type": "string", - "title": "Notes", - "description": "Additional details or notes about the task.", - "default": "" + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" }, - "status": { + "kind": { "type": "string", - "enum": [ - "todo", - "in_progress", - "done" - ], - "title": "Status", - "description": "The current status of the task. One of 'todo', 'in_progress', or 'done'.", - "default": "todo" + "const": "TerminalActionWithRisk", + "title": "Kind" } }, + "additionalProperties": false, "type": "object", - "required": [ - "title" - ], - "title": "TaskItem" + "required": ["command", "kind"], + "title": "TerminalActionWithRisk" }, - "TaskTrackerAction": { + "TerminalObservation": { "properties": { - "kind": { - "type": "string", - "const": "TaskTrackerAction", - "title": "Kind", - "default": "TaskTrackerAction" + "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": [ - "view", - "plan" + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } ], "title": "Command", - "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.", - "default": "view" + "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." }, - "task_list": { - "items": { - "$ref": "#/components/schemas/TaskItem" - }, - "type": "array", - "title": "Task List", - "description": "The full task list. Required parameter of `plan` command." + "exit_code": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Exit Code", + "description": "The exit code of the command. -1 indicates the process hit the soft timeout and is not yet finished." + }, + "timeout": { + "type": "boolean", + "title": "Timeout", + "description": "Whether the command execution timed out.", + "default": false + }, + "metadata": { + "$ref": "#/components/schemas/CmdOutputMetadata", + "description": "Additional metadata captured from PS1 after command execution." + }, + "full_output_save_dir": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Full Output Save Dir", + "description": "Directory where full output files are saved" + }, + "kind": { + "type": "string", + "const": "TerminalObservation", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "title": "TaskTrackerAction", - "description": "An action where the agent writes or updates a task list for task management." + "required": ["command", "kind"], + "title": "TerminalObservation", + "description": "A ToolResult that can be rendered as a CLI output." }, - "TaskTrackerObservation": { + "TerminalTool": { "properties": { - "kind": { + "description": { "type": "string", - "const": "TaskTrackerObservation", - "title": "Kind", - "default": "TaskTrackerObservation" + "title": "Description" }, - "content": { + "action_type": { "type": "string", - "title": "Content", - "description": "The formatted task list or status message", - "default": "" + "title": "Action Type" }, - "command": { - "type": "string", - "title": "Command", - "description": "The command that was executed", - "default": "" + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" }, - "task_list": { - "items": { - "$ref": "#/components/schemas/TaskItem" - }, - "type": "array", - "title": "Task List", - "description": "The current task list" - } - }, - "additionalProperties": false, - "type": "object", - "title": "TaskTrackerObservation", - "description": "This data class represents the result of a task tracking operation." - }, - "TaskTrigger": { - "properties": { - "type": { + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { "type": "string", - "const": "task", - "title": "Type", - "default": "task" + "const": "TerminalTool", + "title": "Kind" }, - "triggers": { - "items": { - "type": "string" - }, - "type": "array", - "title": "Triggers" + "title": { + "type": "string", + "title": "Title", + "readOnly": true } }, "type": "object", - "required": [ - "triggers" - ], - "title": "TaskTrigger", - "description": "Trigger for task-specific skills.\n\nThese skills are activated for specific task types and can modify prompts." + "required": ["description", "action_type", "kind", "title"], + "title": "TerminalTool", + "description": "A ToolDefinition subclass that automatically initializes a TerminalExecutor with auto-detection." }, "TextContent": { "properties": { @@ -5672,52 +17125,144 @@ }, "additionalProperties": false, "type": "object", - "required": [ - "text" - ], + "required": ["text"], "title": "TextContent" }, "ThinkAction": { "properties": { + "thought": { + "type": "string", + "title": "Thought", + "description": "The thought to log." + }, "kind": { "type": "string", "const": "ThinkAction", - "title": "Kind", - "default": "ThinkAction" - }, + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["thought", "kind"], + "title": "ThinkAction", + "description": "Action for logging a thought without making any changes." + }, + "ThinkActionWithRisk": { + "properties": { "thought": { "type": "string", "title": "Thought", "description": "The thought to log." + }, + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" + }, + "kind": { + "type": "string", + "const": "ThinkActionWithRisk", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "thought" - ], - "title": "ThinkAction", - "description": "Action for logging a thought without making any changes." + "required": ["thought", "kind"], + "title": "ThinkActionWithRisk" }, "ThinkObservation": { "properties": { + "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 + }, "kind": { "type": "string", "const": "ThinkObservation", - "title": "Kind", - "default": "ThinkObservation" - }, - "content": { - "type": "string", - "title": "Content", - "description": "Confirmation message.", - "default": "Your thought has been logged." + "title": "Kind" } }, "additionalProperties": false, "type": "object", + "required": ["kind"], "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." + }, + "ThinkTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "action_type": { + "type": "string", + "title": "Action Type" + }, + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" + }, + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] + }, + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" + }, + "kind": { + "type": "string", + "const": "ThinkTool", + "title": "Kind" + }, + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "ThinkTool", + "description": "Tool for logging thoughts without making changes." }, "ThinkingBlock": { "properties": { @@ -5733,19 +17278,68 @@ "description": "The thinking content" }, "signature": { - "type": "string", + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], "title": "Signature", "description": "Cryptographic signature for the thinking block" } }, "type": "object", - "required": [ - "thinking", - "signature" - ], + "required": ["thinking"], "title": "ThinkingBlock", "description": "Anthropic thinking block for extended thinking feature.\n\nThis represents the raw thinking blocks returned by Anthropic models\nwhen extended thinking is enabled. These blocks must be preserved\nand passed back to the API for tool use scenarios." }, + "TokenEvent": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Unique event id (ULID/UUID)" + }, + "timestamp": { + "type": "string", + "title": "Timestamp", + "description": "Event timestamp" + }, + "source": { + "type": "string", + "enum": ["agent", "user", "environment", "hook"], + "title": "Source" + }, + "prompt_token_ids": { + "items": { + "type": "integer" + }, + "type": "array", + "title": "Prompt Token Ids", + "description": "The exact prompt token IDs for this message event" + }, + "response_token_ids": { + "items": { + "type": "integer" + }, + "type": "array", + "title": "Response Token Ids", + "description": "The exact response token IDs for this message event" + }, + "kind": { + "type": "string", + "const": "TokenEvent", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["source", "prompt_token_ids", "response_token_ids", "kind"], + "title": "TokenEvent", + "description": "Event from VLLM representing token IDs used in LLM interaction." + }, "TokenUsage": { "properties": { "model": { @@ -5812,17 +17406,13 @@ "title": "TokenUsage", "description": "Metric tracking detailed token usage per completion call." }, - "Tool": { + "Tool-Input": { "properties": { "name": { "type": "string", "title": "Name", - "description": "Name of the tool class, e.g., 'BashTool'. Import it from an `openhands.tools.` subpackage.", - "examples": [ - "BashTool", - "FileEditorTool", - "TaskTrackerTool" - ] + "description": "Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage.", + "examples": ["TerminalTool", "FileEditorTool", "TaskTrackerTool"] }, "params": { "additionalProperties": true, @@ -5833,30 +17423,208 @@ { "working_dir": "/workspace" } - ] + ] + } + }, + "type": "object", + "required": ["name"], + "title": "Tool", + "description": "Defines a tool to be initialized for the agent.\n\nThis is only used in agent-sdk for type schema for server use." + }, + "ToolDefinition": { + "oneOf": [ + { + "$ref": "#/components/schemas/MCPToolDefinition" + }, + { + "$ref": "#/components/schemas/FinishTool" + }, + { + "$ref": "#/components/schemas/InvokeSkillTool" + }, + { + "$ref": "#/components/schemas/SwitchLLMTool" + }, + { + "$ref": "#/components/schemas/ThinkTool" + }, + { + "$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/DelegateTool" + }, + { + "$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" + } + ], + "discriminator": { + "propertyName": "kind", + "mapping": { + "openhands__sdk__mcp__tool__MCPToolDefinition-Output__1": "#/components/schemas/MCPToolDefinition", + "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__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__delegate__definition__DelegateTool-Output__1": "#/components/schemas/DelegateTool", + "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" + } + } + }, + "ToolExecution": { + "properties": { + "taskSupport": { + "anyOf": [ + { + "type": "string", + "enum": ["forbidden", "optional", "required"] + }, + { + "type": "null" + } + ], + "title": "Tasksupport" } }, + "additionalProperties": true, "type": "object", - "required": [ - "name" - ], - "title": "Tool", - "description": "Defines a tool to be initialized for the agent.\n\nThis is only used in agent-sdk for type schema for server use." + "title": "ToolExecution", + "description": "Execution-related properties for a tool." }, "UpdateConversationRequest": { "properties": { "title": { - "type": "string", - "maxLength": 200, - "minLength": 1, + "anyOf": [ + { + "type": "string", + "maxLength": 200, + "minLength": 1 + }, + { + "type": "null" + } + ], "title": "Title", "description": "New conversation title" + }, + "tags": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Tags", + "description": "Key-value tags to set on the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters. Replaces all existing tags when provided." } }, "type": "object", - "required": [ - "title" - ], "title": "UpdateConversationRequest", "description": "Payload to update conversation metadata." }, @@ -5864,21 +17632,7 @@ "properties": { "secrets": { "additionalProperties": { - "oneOf": [ - { - "$ref": "#/components/schemas/LookupSecret" - }, - { - "$ref": "#/components/schemas/StaticSecret" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__conversation__secret_source__LookupSecret-Input__1": "#/components/schemas/LookupSecret", - "openhands__sdk__conversation__secret_source__StaticSecret-Input__1": "#/components/schemas/StaticSecret" - } - } + "$ref": "#/components/schemas/SecretSource-Input" }, "type": "object", "title": "Secrets", @@ -5886,20 +17640,12 @@ } }, "type": "object", - "required": [ - "secrets" - ], + "required": ["secrets"], "title": "UpdateSecretsRequest", "description": "Payload to update secrets in a conversation." }, "UserRejectObservation": { "properties": { - "kind": { - "type": "string", - "const": "UserRejectObservation", - "title": "Kind", - "default": "UserRejectObservation" - }, "id": { "type": "string", "title": "Id", @@ -5912,11 +17658,7 @@ }, "source": { "type": "string", - "enum": [ - "agent", - "user", - "environment" - ], + "enum": ["agent", "user", "environment", "hook"], "title": "Source", "default": "environment" }, @@ -5936,21 +17678,29 @@ "description": "Reason for rejecting the action", "default": "User rejected the action" }, + "rejection_source": { + "type": "string", + "enum": ["user", "hook"], + "title": "Rejection Source", + "description": "Source of the rejection: 'user' for confirmation mode rejections, 'hook' for PreToolUse hook blocks", + "default": "user" + }, "action_id": { "type": "string", "title": "Action Id", "description": "The action id that this observation is responding to" + }, + "kind": { + "type": "string", + "const": "UserRejectObservation", + "title": "Kind" } }, "additionalProperties": false, "type": "object", - "required": [ - "tool_name", - "tool_call_id", - "action_id" - ], + "required": ["tool_name", "tool_call_id", "action_id", "kind"], "title": "UserRejectObservation", - "description": "Observation when user rejects an action in confirmation mode." + "description": "Observation when an action is rejected by user or hook.\n\nThis event is emitted when:\n- User rejects an action during confirmation mode (rejection_source=\"user\")\n- A PreToolUse hook blocks an action (rejection_source=\"hook\")" }, "VSCodeUrlResponse": { "properties": { @@ -5967,9 +17717,7 @@ } }, "type": "object", - "required": [ - "url" - ], + "required": ["url"], "title": "VSCodeUrlResponse", "description": "Response model for VSCode URL." }, @@ -5996,261 +17744,453 @@ "type": { "type": "string", "title": "Error Type" + }, + "input": { + "title": "Input" + }, + "ctx": { + "type": "object", + "title": "Context" } }, "type": "object", - "required": [ - "loc", - "msg", - "type" - ], + "required": ["loc", "msg", "type"], "title": "ValidationError" }, - "Event": { - "oneOf": [ - { - "$ref": "#/components/schemas/Condensation" + "VerifiedModelsResponse": { + "properties": { + "models": { + "additionalProperties": { + "items": { + "type": "string" + }, + "type": "array" + }, + "type": "object", + "title": "Models" + } + }, + "type": "object", + "required": ["models"], + "title": "VerifiedModelsResponse", + "description": "Response containing verified models organized by provider." + }, + "WriteFileAction": { + "properties": { + "file_path": { + "type": "string", + "title": "File Path", + "description": "The path to the file to write to." }, - { - "$ref": "#/components/schemas/CondensationRequest" + "content": { + "type": "string", + "title": "Content", + "description": "The content to write to the file." }, - { - "$ref": "#/components/schemas/CondensationSummaryEvent" + "kind": { + "type": "string", + "const": "WriteFileAction", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["file_path", "content", "kind"], + "title": "WriteFileAction", + "description": "Schema for write file operation." + }, + "WriteFileActionWithRisk": { + "properties": { + "file_path": { + "type": "string", + "title": "File Path", + "description": "The path to the file to write to." }, - { - "$ref": "#/components/schemas/ConversationStateUpdateEvent" + "content": { + "type": "string", + "title": "Content", + "description": "The content to write to the file." }, - { - "$ref": "#/components/schemas/ActionEvent" + "security_risk": { + "$ref": "#/components/schemas/SecurityRisk", + "description": "The LLM's assessment of the safety risk of this action.", + "default": "UNKNOWN" }, - { - "$ref": "#/components/schemas/MessageEvent" + "kind": { + "type": "string", + "const": "WriteFileActionWithRisk", + "title": "Kind" + } + }, + "additionalProperties": false, + "type": "object", + "required": ["file_path", "content", "kind"], + "title": "WriteFileActionWithRisk" + }, + "WriteFileObservation": { + "properties": { + "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." }, - { - "$ref": "#/components/schemas/AgentErrorEvent" + "is_error": { + "type": "boolean", + "title": "Is Error", + "description": "Whether the observation indicates an error", + "default": false }, - { - "$ref": "#/components/schemas/ObservationEvent" + "file_path": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "File Path", + "description": "The file path that was written." }, - { - "$ref": "#/components/schemas/UserRejectObservation" + "is_new_file": { + "type": "boolean", + "title": "Is New File", + "description": "Whether a new file was created.", + "default": false }, - { - "$ref": "#/components/schemas/SystemPromptEvent" + "old_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Old Content", + "description": "The previous content of the file (if it existed)." }, - { - "$ref": "#/components/schemas/PauseEvent" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "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_state__ConversationStateUpdateEvent-Output__1": "#/components/schemas/ConversationStateUpdateEvent", - "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__user_action__PauseEvent-Output__1": "#/components/schemas/PauseEvent" - } - }, - "title": "Event" - }, - "BashEventBase": { - "oneOf": [ - { - "$ref": "#/components/schemas/BashCommand" + "new_content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "New Content", + "description": "The new content written to the file." }, - { - "$ref": "#/components/schemas/BashOutput" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__agent_server__models__BashCommand-Output__1": "#/components/schemas/BashCommand", - "openhands__agent_server__models__BashOutput-Output__1": "#/components/schemas/BashOutput" + "kind": { + "type": "string", + "const": "WriteFileObservation", + "title": "Kind" } }, - "title": "BashEventBase" + "additionalProperties": false, + "type": "object", + "required": ["kind"], + "title": "WriteFileObservation", + "description": "Observation from writing a file." }, - "Action": { - "oneOf": [ - { - "$ref": "#/components/schemas/MCPToolAction" - }, - { - "$ref": "#/components/schemas/FinishAction" + "WriteFileTool": { + "properties": { + "description": { + "type": "string", + "title": "Description" }, - { - "$ref": "#/components/schemas/ThinkAction" + "action_type": { + "type": "string", + "title": "Action Type" }, - { - "$ref": "#/components/schemas/BrowserClickAction" + "observation_type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Observation Type" }, - { - "$ref": "#/components/schemas/BrowserCloseTabAction" + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/openhands__sdk__tool__tool__ToolAnnotations" + }, + { + "type": "null" + } + ] }, - { - "$ref": "#/components/schemas/BrowserGetContentAction" + "meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" }, - { - "$ref": "#/components/schemas/BrowserGetStateAction" + "kind": { + "type": "string", + "const": "WriteFileTool", + "title": "Kind" }, - { - "$ref": "#/components/schemas/BrowserGoBackAction" + "title": { + "type": "string", + "title": "Title", + "readOnly": true + } + }, + "type": "object", + "required": ["description", "action_type", "kind", "title"], + "title": "WriteFileTool", + "description": "Tool for writing complete file contents." + }, + "mcp__types__Tool": { + "properties": { + "name": { + "type": "string", + "title": "Name" }, - { - "$ref": "#/components/schemas/BrowserListTabsAction" + "title": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title" }, - { - "$ref": "#/components/schemas/BrowserNavigateAction" + "description": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Description" }, - { - "$ref": "#/components/schemas/BrowserScrollAction" + "inputSchema": { + "additionalProperties": true, + "type": "object", + "title": "Inputschema" }, - { - "$ref": "#/components/schemas/BrowserSwitchTabAction" + "outputSchema": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Outputschema" }, - { - "$ref": "#/components/schemas/BrowserTypeAction" + "icons": { + "anyOf": [ + { + "items": { + "$ref": "#/components/schemas/Icon" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Icons" }, - { - "$ref": "#/components/schemas/ExecuteBashAction" + "annotations": { + "anyOf": [ + { + "$ref": "#/components/schemas/mcp__types__ToolAnnotations" + }, + { + "type": "null" + } + ] }, - { - "$ref": "#/components/schemas/FileEditorAction" + "_meta": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Meta" }, - { - "$ref": "#/components/schemas/TaskTrackerAction" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "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__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__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__BrowserSwitchTabAction-Output__1": "#/components/schemas/BrowserSwitchTabAction", - "openhands__tools__browser_use__definition__BrowserTypeAction-Output__1": "#/components/schemas/BrowserTypeAction", - "openhands__tools__execute_bash__definition__ExecuteBashAction-Output__1": "#/components/schemas/ExecuteBashAction", - "openhands__tools__file_editor__definition__FileEditorAction-Output__1": "#/components/schemas/FileEditorAction", - "openhands__tools__task_tracker__definition__TaskTrackerAction-Output__1": "#/components/schemas/TaskTrackerAction" + "execution": { + "anyOf": [ + { + "$ref": "#/components/schemas/ToolExecution" + }, + { + "type": "null" + } + ] } }, - "title": "Action" + "additionalProperties": true, + "type": "object", + "required": ["name", "inputSchema"], + "title": "Tool", + "description": "Definition for a tool the client can call." }, - "CondenserBase": { - "oneOf": [ - { - "$ref": "#/components/schemas/LLMSummarizingCondenser" + "mcp__types__ToolAnnotations": { + "properties": { + "title": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title" }, - { - "$ref": "#/components/schemas/NoOpCondenser" + "readOnlyHint": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Readonlyhint" }, - { - "$ref": "#/components/schemas/PipelineCondenser-Output" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__context__condenser__llm_summarizing_condenser__LLMSummarizingCondenser-Output__1": "#/components/schemas/LLMSummarizingCondenser", - "openhands__sdk__context__condenser__no_op_condenser__NoOpCondenser-Output__1": "#/components/schemas/NoOpCondenser", - "openhands__sdk__context__condenser__pipeline_condenser__PipelineCondenser-Output__1": "#/components/schemas/PipelineCondenser-Output" - } - }, - "title": "CondenserBase" - }, - "BaseWorkspace": { - "oneOf": [ - { - "$ref": "#/components/schemas/LocalWorkspace" + "destructiveHint": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Destructivehint" }, - { - "$ref": "#/components/schemas/RemoteWorkspace" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__workspace__local__LocalWorkspace-Output__1": "#/components/schemas/LocalWorkspace", - "openhands__sdk__workspace__remote__base__RemoteWorkspace-Output__1": "#/components/schemas/RemoteWorkspace" + "idempotentHint": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Idempotenthint" + }, + "openWorldHint": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Openworldhint" } }, - "title": "BaseWorkspace" + "additionalProperties": true, + "type": "object", + "title": "ToolAnnotations", + "description": "Additional properties describing a Tool to clients.\n\nNOTE: all properties in ToolAnnotations are **hints**.\nThey are not guaranteed to provide a faithful description of\ntool behavior (including descriptive properties like `title`).\n\nClients should never make tool use decisions based on ToolAnnotations\nreceived from untrusted servers." }, - "ConfirmationPolicyBase": { - "oneOf": [ - { - "$ref": "#/components/schemas/AlwaysConfirm" - }, - { - "$ref": "#/components/schemas/ConfirmRisky" + "openhands__sdk__tool__spec__Tool": { + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "Name of the tool class, e.g., 'TerminalTool'. Import it from an `openhands.tools.` subpackage.", + "examples": ["TerminalTool", "FileEditorTool", "TaskTrackerTool"] }, - { - "$ref": "#/components/schemas/NeverConfirm" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__security__confirmation_policy__AlwaysConfirm-Output__1": "#/components/schemas/AlwaysConfirm", - "openhands__sdk__security__confirmation_policy__ConfirmRisky-Output__1": "#/components/schemas/ConfirmRisky", - "openhands__sdk__security__confirmation_policy__NeverConfirm-Output__1": "#/components/schemas/NeverConfirm" + "params": { + "additionalProperties": true, + "type": "object", + "title": "Params", + "description": "Parameters for the tool's .create() method, e.g., {'working_dir': '/app'}", + "examples": [ + { + "working_dir": "/workspace" + } + ] } }, - "title": "ConfirmationPolicyBase" + "type": "object", + "required": ["name"], + "title": "Tool", + "description": "Defines a tool to be initialized for the agent.\n\nThis is only used in agent-sdk for type schema for server use." }, - "Observation": { - "oneOf": [ - { - "$ref": "#/components/schemas/MCPToolObservation" - }, - { - "$ref": "#/components/schemas/FinishObservation" - }, - { - "$ref": "#/components/schemas/ThinkObservation" + "openhands__sdk__tool__tool__ToolAnnotations": { + "properties": { + "title": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title", + "description": "A human-readable title for the tool." }, - { - "$ref": "#/components/schemas/BrowserObservation" + "readOnlyHint": { + "type": "boolean", + "title": "Readonlyhint", + "description": "If true, the tool does not modify its environment. Default: false", + "default": false }, - { - "$ref": "#/components/schemas/ExecuteBashObservation" + "destructiveHint": { + "type": "boolean", + "title": "Destructivehint", + "description": "If true, the tool may perform destructive updates to its environment. If false, the tool performs only additive updates. (This property is meaningful only when `readOnlyHint == false`) Default: true", + "default": true }, - { - "$ref": "#/components/schemas/FileEditorObservation" + "idempotentHint": { + "type": "boolean", + "title": "Idempotenthint", + "description": "If true, calling the tool repeatedly with the same arguments will have no additional effect on the its environment. (This property is meaningful only when `readOnlyHint == false`) Default: false", + "default": false }, - { - "$ref": "#/components/schemas/TaskTrackerObservation" - } - ], - "discriminator": { - "propertyName": "kind", - "mapping": { - "openhands__sdk__mcp__definition__MCPToolObservation-Output__1": "#/components/schemas/MCPToolObservation", - "openhands__sdk__tool__builtins__finish__FinishObservation-Output__1": "#/components/schemas/FinishObservation", - "openhands__sdk__tool__builtins__think__ThinkObservation-Output__1": "#/components/schemas/ThinkObservation", - "openhands__tools__browser_use__definition__BrowserObservation-Output__1": "#/components/schemas/BrowserObservation", - "openhands__tools__execute_bash__definition__ExecuteBashObservation-Output__1": "#/components/schemas/ExecuteBashObservation", - "openhands__tools__file_editor__definition__FileEditorObservation-Output__1": "#/components/schemas/FileEditorObservation", - "openhands__tools__task_tracker__definition__TaskTrackerObservation-Output__1": "#/components/schemas/TaskTrackerObservation" + "openWorldHint": { + "type": "boolean", + "title": "Openworldhint", + "description": "If true, this tool may interact with an 'open world' of external entities. If false, the tool's domain of interaction is closed. For example, the world of a web search tool is open, whereas that of a memory tool is not. Default: true", + "default": true } }, - "title": "Observation" + "type": "object", + "title": "openhands.sdk.tool.tool.ToolAnnotations", + "description": "Annotations to provide hints about the tool's behavior.\n\nBased on Model Context Protocol (MCP) spec:\nhttps://github.com/modelcontextprotocol/modelcontextprotocol/blob/caf3424488b10b4a7b1f8cb634244a450a1f4400/schema/2025-06-18/schema.ts#L838" } } }