> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-chore-regenerate-agent-sdk-openapi.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Switch Conversation Llm > 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), and by the frontend's per-conversation model switch, which forwards a profile config that may reference a saved provider connection by id instead of carrying an inline API key. ## OpenAPI ````yaml /openapi/agent-sdk.json post /api/conversations/{conversation_id}/switch_llm openapi: 3.1.0 info: description: OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent title: OpenHands Agent Server version: 1.52.0 servers: [] security: [] paths: /api/conversations/{conversation_id}/switch_llm: post: tags: - Conversations summary: 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), and by the frontend's per-conversation model switch, which forwards a profile config that may reference a saved provider connection by id instead of carrying an inline API key. operationId: >- switch_conversation_llm_api_conversations__conversation_id__switch_llm_post parameters: - in: path name: conversation_id required: true schema: format: uuid title: Conversation Id type: string requestBody: content: application/json: schema: $ref: >- #/components/schemas/Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Success' description: Successful Response '404': description: Conversation not found '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - APIKeyHeader: [] components: schemas: Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post: properties: llm: $ref: '#/components/schemas/LLM-Input' required: - llm title: >- Body_switch_conversation_llm_api_conversations__conversation_id__switch_llm_post type: object Success: properties: success: default: true title: Success type: boolean title: Success type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object LLM-Input: description: >- Language model interface for OpenHands agents. The LLM class provides a unified interface for interacting with various language models through the litellm library. It handles model configuration, API authentication, retry logic, and tool calling capabilities. Attributes: model: Model name (e.g., "gpt-5.6"). api_key: API key for authentication. base_url: Custom API base URL. num_retries: Number of retry attempts for failed requests. timeout: Request timeout in seconds. Example: ```python from openhands.sdk import LLM from pydantic import SecretStr llm = LLM( model="gpt-5.6", api_key=SecretStr("your-api-key"), usage_id="my-agent" ) # Use with agent or conversation ``` properties: api_key: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' description: API key. openhands_settings: depends_on: [] label: API Key prominence: critical title: Api Key api_mode: default: auto description: >- LLM API endpoint mode. 'auto' resolves from model metadata and SDK fallbacks; use 'chat' or 'responses' to override endpoint selection for proxy aliases and newly released models. enum: - auto - chat - responses openhands_settings: depends_on: [] prominence: minor title: Api Mode type: string api_version: anyOf: - type: string - type: 'null' description: API version (e.g., Azure). openhands_settings: depends_on: [] prominence: minor title: Api Version auth_type: default: api_key description: Authentication mode for the LLM. enum: - api_key - subscription openhands_settings: depends_on: [] label: Authentication prominence: critical title: Auth Type type: string aws_access_key_id: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Access Key Id aws_bedrock_runtime_endpoint: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Bedrock Runtime Endpoint aws_profile_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Profile Name aws_region_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Region Name aws_role_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Role Name aws_secret_access_key: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Secret Access Key aws_session_name: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Session Name aws_session_token: anyOf: - type: string - format: password type: string writeOnly: true - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Aws Session Token base_url: anyOf: - type: string - type: 'null' description: Custom base URL. openhands_settings: depends_on: [] prominence: major title: Base Url caching_prompt: default: true description: Enable caching of prompts. openhands_settings: depends_on: [] prominence: minor title: Caching Prompt type: boolean capability_overrides: additionalProperties: anyOf: - type: boolean - type: string description: >- Explicit model capability overrides. Supported keys include supports_reasoning_effort, thinking_mode (adaptive, manual, none, or unknown), supports_sampling_params, supports_prompt_cache, supports_stop_words, supports_responses_api, supports_vision, and supports_prompt_cache_retention. Overrides take precedence over LiteLLM metadata and SDK fallbacks. openhands_settings: depends_on: [] prominence: minor title: Capability Overrides type: object custom_tokenizer: anyOf: - type: string - type: 'null' description: A custom tokenizer to use for token counting. openhands_settings: depends_on: [] prominence: minor title: Custom Tokenizer disable_stop_word: anyOf: - type: boolean - type: 'null' default: false description: Disable using of stop word. openhands_settings: depends_on: [] prominence: minor title: Disable Stop Word disable_vision: anyOf: - type: boolean - type: 'null' description: >- If model is vision capable, this option allows to disable image processing (useful for cost reduction). openhands_settings: depends_on: [] prominence: minor title: Disable Vision drop_params: default: true openhands_settings: depends_on: [] prominence: minor title: Drop Params type: boolean enable_encrypted_reasoning: default: true description: >- If True, ask for ['reasoning.encrypted_content'] in Responses API include. openhands_settings: depends_on: [] prominence: minor title: Enable Encrypted Reasoning type: boolean extended_thinking_budget: anyOf: - type: integer - type: 'null' default: 200000 description: >- Legacy token budget for models confirmed to use manual Anthropic extended thinking. Ignored for adaptive-thinking models. Prefer reasoning_effort for new integrations. openhands_settings: depends_on: [] prominence: minor title: Extended Thinking Budget extra_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' description: Optional HTTP headers to forward to LiteLLM requests. openhands_settings: depends_on: [] prominence: minor title: Extra Headers 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. force_string_serializer: anyOf: - type: boolean - type: 'null' description: >- Force using string content serializer when sending to LLM API. If None (default), auto-detect based on model. Useful for providers that do not support list content, like HuggingFace and Groq. openhands_settings: depends_on: [] prominence: minor title: Force String Serializer inline_image_urls: anyOf: - type: boolean - type: 'null' description: >- If True, fetch any http(s) image URL in outgoing messages and inline it as a base64 ``data:`` URL before sending. If None (default), auto-detect based on model (some APIs such as Moonshot's public Kimi endpoint reject URL-formatted images and require base64). Set this explicitly when the model is reached through a proxy alias that hides the underlying provider (e.g. ``litellm_proxy/``). Note: inlining only runs when ``vision_is_active()`` is True, so the alias must still be recognised as vision-capable by the SDK feature registry or proxy model metadata. openhands_settings: depends_on: [] prominence: minor title: Inline Image Urls input_cost_per_token: anyOf: - minimum: 0 type: number - type: 'null' description: The cost per input token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor title: Input Cost Per Token litellm_extra_body: additionalProperties: true description: >- Additional key-value pairs to pass to litellm's extra_body parameter. This is useful for custom inference endpoints that need additional parameters for configuration, routing, or advanced features. NOTE: Not all LLM providers support extra_body parameters. Some providers (e.g., OpenAI) may reject requests with unrecognized options. This is commonly supported by: - LiteLLM proxy servers (routing metadata, tracing) - vLLM endpoints (return_token_ids, etc.) - Custom inference clusters Examples: - Proxy routing: {'trace_version': '1.0.0', 'tags': ['agent:my-agent']} - vLLM features: {'return_token_ids': True} openhands_settings: depends_on: [] prominence: minor title: Litellm Extra Body type: object log_completions: default: false description: Enable logging of completions. openhands_settings: depends_on: [] prominence: minor title: Log Completions type: boolean log_completions_folder: default: logs/completions description: >- The folder to log LLM completions to. Required if log_completions is True. openhands_settings: depends_on: [] prominence: minor title: Log Completions Folder type: string max_input_tokens: anyOf: - minimum: 1 type: integer - type: 'null' description: >- The maximum number of input tokens. Note that this is currently unused, and the value at runtime is actually the total tokens in OpenAI (e.g. 128,000 tokens for GPT-4). openhands_settings: depends_on: [] prominence: minor title: Max Input Tokens max_message_chars: default: 30000 description: Approx max chars in each event/content sent to the LLM. minimum: 1 openhands_settings: depends_on: [] prominence: minor title: Max Message Chars type: integer max_output_tokens: anyOf: - minimum: 1 type: integer - type: 'null' description: The maximum number of output tokens. This is sent to the LLM. openhands_settings: depends_on: [] prominence: minor title: Max Output Tokens model: default: gpt-5.6 description: Model name. openhands_settings: depends_on: [] prominence: critical title: Model type: string model_canonical_name: anyOf: - type: string - type: 'null' description: >- Optional canonical model name for feature registry lookups. The OpenHands SDK maintains a model feature registry that maps model names to capabilities (e.g., vision support, prompt caching, responses API support). When using proxied or aliased model identifiers, set this field to the canonical model name (e.g., 'openai/gpt-4o') to ensure correct capability detection. If not provided, the 'model' field will be used for capability lookups. openhands_settings: depends_on: [] prominence: minor title: Model Canonical Name native_tool_calling: default: true description: Whether to use native tool calling. openhands_settings: depends_on: [] prominence: minor title: Native Tool Calling type: boolean num_retries: default: 5 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Num Retries type: integer ollama_base_url: anyOf: - type: string - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Ollama Base Url openrouter_app_name: default: OpenHands openhands_settings: depends_on: [] prominence: minor title: Openrouter App Name type: string openrouter_site_url: default: https://docs.all-hands.dev/ openhands_settings: depends_on: [] prominence: minor title: Openrouter Site Url type: string output_cost_per_token: anyOf: - minimum: 0 type: number - type: 'null' description: The cost per output token. This will available in logs for user. openhands_settings: depends_on: [] prominence: minor title: Output Cost Per Token prompt_cache_retention: anyOf: - type: string - type: 'null' default: 24h description: >- Retention policy for prompt cache. Only sent for supported models (GPT-5+ and GPT-4.1, excluding Azure deployments); explicitly stripped for all others. openhands_settings: depends_on: [] prominence: minor title: Prompt Cache Retention provider_connection_id: anyOf: - type: string - type: 'null' description: >- Optional provider connection whose shared API key and base URL are resolved and applied each time this LLM profile is loaded (read-at-use). When set, the profile stores no inline api_key or base_url of its own. openhands_settings: depends_on: [] prominence: major title: Provider Connection Id reasoning_effort: anyOf: - enum: - low - medium - high - xhigh - none type: string - type: 'null' default: high description: >- Provider-neutral reasoning effort. Common values include 'none', 'minimal', 'low', 'medium', 'high', 'xhigh', and 'max'. The SDK accepts future provider values and lets LiteLLM translate them. openhands_settings: depends_on: [] prominence: minor title: Reasoning Effort reasoning_summary: anyOf: - enum: - auto - concise - detailed type: string - type: 'null' description: >- The level of detail for reasoning summaries. This is a string that can be one of 'auto', 'concise', or 'detailed'. Requires verified OpenAI organization. Only sent when explicitly set. openhands_settings: depends_on: [] prominence: minor title: Reasoning Summary retry_max_wait: default: 64 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Retry Max Wait type: integer retry_min_wait: default: 8 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Retry Min Wait type: integer retry_multiplier: default: 8 minimum: 0 openhands_settings: depends_on: [] prominence: minor title: Retry Multiplier type: number seed: anyOf: - type: integer - type: 'null' description: The seed to use for random number generation. openhands_settings: depends_on: [] prominence: minor title: Seed stream: default: false description: >- Enable streaming responses from the LLM. When enabled, the provided `on_token` callback in .completions and .responses will be invoked for each chunk of tokens. openhands_settings: depends_on: [] prominence: minor title: Stream type: boolean stream_idle_timeout: anyOf: - minimum: 0 type: number - type: 'null' default: 300 description: >- Maximum seconds between chunks in an asynchronous streaming response. Default is 300s (5 minutes); set to None to disable. openhands_settings: depends_on: [] prominence: minor title: Stream Idle Timeout subscription_vendor: anyOf: - const: openai type: string - type: 'null' description: Subscription provider for subscription-backed LLM access. openhands_settings: depends_on: - auth_type label: Subscription provider prominence: critical title: Subscription Vendor temperature: anyOf: - minimum: 0 type: number - type: 'null' description: >- Sampling temperature for response generation. Defaults to None (uses provider default temperature). Set to 0.0 for deterministic outputs, or higher values (0.7-1.0) for more creative responses. openhands_settings: depends_on: [] prominence: minor title: Temperature timeout: anyOf: - minimum: 0 type: integer - type: 'null' default: 300 description: >- HTTP and hard per-attempt timeout in seconds. Default is 300s (5 minutes). Set to None to disable the hard timeout. openhands_settings: depends_on: [] prominence: minor title: Timeout top_k: anyOf: - minimum: 0 type: number - type: 'null' openhands_settings: depends_on: [] prominence: minor title: Top K top_p: anyOf: - maximum: 1 minimum: 0 type: number - type: 'null' description: >- Nucleus sampling parameter. Defaults to None (uses provider default). Set to a value between 0 and 1 to control diversity of outputs. openhands_settings: depends_on: [] prominence: minor title: Top P usage_id: default: default description: >- Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking. openhands_settings: depends_on: [] prominence: minor title: Usage Id type: string title: LLM type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object 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. properties: fallback_llms: description: Ordered list of LLM profile names to try on transient failure. items: type: string title: Fallback Llms type: array profile_store_dir: anyOf: - type: string - format: path type: string - type: 'null' description: >- Path to directory containing profiles. If not specified, defaults to `.openhands/profiles`. title: Profile Store Dir required: - fallback_llms title: FallbackStrategy type: object securitySchemes: APIKeyHeader: in: header name: X-Session-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.