Start Conversation

Start a conversation in the local environment.

POST /api/conversations

Try it

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "llm": {
      "model": "claude-sonnet-4-20250514",
      "api_key": "<string>",
      "base_url": "<string>",
      "api_version": "<string>",
      "aws_access_key_id": "<string>",
      "aws_secret_access_key": "<string>",
      "aws_region_name": "<string>",
      "openrouter_site_url": "https://docs.all-hands.dev/",
      "openrouter_app_name": "OpenHands",
      "num_retries": 5,
      "retry_multiplier": 8,
      "retry_min_wait": 8,
      "retry_max_wait": 64,
      "timeout": 1,
      "max_message_chars": 30000,
      "temperature": 1,
      "top_p": 1,
      "top_k": 1,
      "custom_llm_provider": "<string>",
      "max_input_tokens": 2,
      "max_output_tokens": 2,
      "extra_headers": {},
      "input_cost_per_token": 1,
      "output_cost_per_token": 1,
      "ollama_base_url": "<string>",
      "stream": false,
      "drop_params": true,
      "modify_params": true,
      "disable_vision": true,
      "disable_stop_word": false,
      "caching_prompt": true,
      "log_completions": false,
      "log_completions_folder": "logs/completions",
      "custom_tokenizer": "<string>",
      "native_tool_calling": true,
      "force_string_serializer": true,
      "reasoning_effort": "high",
      "reasoning_summary": "auto",
      "enable_encrypted_reasoning": false,
      "prompt_cache_retention": "24h",
      "extended_thinking_budget": 200000,
      "seed": 123,
      "safety_settings": [
        {}
      ],
      "usage_id": "default",
      "litellm_extra_body": {},
      "OVERRIDE_ON_SERIALIZE": [
        "api_key",
        "aws_access_key_id",
        "aws_secret_access_key",
        "litellm_extra_body"
      ]
    },
    "kind": "Agent",
    "tools": [
      {
        "name": "<string>",
        "params": {}
      }
    ],
    "mcp_config": {},
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "agent_context": {
      "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": "system_prompt.j2",
    "system_prompt_kwargs": {},
    "condenser": {
      "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
    }
  },
  "workspace": {
    "working_dir": "<string>",
    "kind": "LocalWorkspace"
  },
  "persistence_dir": "workspace/conversations",
  "max_iterations": 500,
  "stuck_detection": true,
  "execution_status": "idle",
  "confirmation_policy": {
    "kind": "AlwaysConfirm"
  },
  "security_analyzer": {
    "kind": "LLMSecurityAnalyzer"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "stats": {
    "usage_to_metrics": {}
  },
  "secret_registry": {
    "secret_sources": {}
  },
  "title": "<string>",
  "metrics": {
    "model_name": "default",
    "accumulated_cost": 0,
    "max_budget_per_task": 123,
    "accumulated_token_usage": {
      "model": "",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0,
      "context_window": 0,
      "per_turn_token": 0,
      "response_id": ""
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Body

application/json

Payload to create a new conversation.

Contains an Agent configuration along with conversation-specific options.

agent · Agent · object · required

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.

Example: >>> from openhands.sdk import LLM, Agent, Tool >>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key")) >>> tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")] >>> agent = Agent(llm=llm, tools=tools)

Show child attributes

agent. llm · LLM · object · required

LLM configuration for the agent.

Show child attributes

agent.llm. model · string · default: claude-sonnet-4-20250514

Model name.

agent.llm. api_key

API key.

agent.llm. base_url · string | null

Custom base URL.

agent.llm. api_version · string | null

API version (e.g., Azure).

agent.llm. aws_access_key_id

agent.llm. aws_secret_access_key

agent.llm. aws_region_name · string | null

agent.llm. openrouter_site_url · string · default: https://docs.all-hands.dev/

agent.llm. openrouter_app_name · string · default: OpenHands

agent.llm. num_retries · integer · default: 5

Required range: x >= 0

agent.llm. retry_multiplier · number · default: 8

Required range: x >= 0

agent.llm. retry_min_wait · integer · default: 8

Required range: x >= 0

agent.llm. retry_max_wait · integer · default: 64

Required range: x >= 0

agent.llm. timeout · integer | null

HTTP timeout (s).

Required range: x >= 0

agent.llm. max_message_chars · integer · default: 30000

Approx max chars in each event/content sent to the LLM.

Required range: x >= 1

agent.llm. temperature · number | null

Sampling temperature for response generation. Defaults to 0 for most models and provider default for reasoning models.

Required range: x >= 0

agent.llm. top_p · number | null · default: 1

Required range: 0 <= x <= 1

agent.llm. top_k · number | null

Required range: x >= 0

agent.llm. custom_llm_provider · string | null

agent.llm. max_input_tokens · integer | null

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).

Required range: x >= 1

agent.llm. max_output_tokens · integer | null

The maximum number of output tokens. This is sent to the LLM.

Required range: x >= 1

agent.llm. extra_headers · Extra Headers · object

Optional HTTP headers to forward to LiteLLM requests.

Show child attributes

agent.llm.extra_headers. {key} · string

agent.llm. input_cost_per_token · number | null

The cost per input token. This will available in logs for user.

Required range: x >= 0

agent.llm. output_cost_per_token · number | null

The cost per output token. This will available in logs for user.

Required range: x >= 0

agent.llm. ollama_base_url · string | null

agent.llm. stream · boolean · default: false

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.

agent.llm. drop_params · boolean · default: true

agent.llm. modify_params · boolean · default: true

Modify params allows litellm to do transformations like adding a default message, when a message is empty.

agent.llm. disable_vision · boolean | null

If model is vision capable, this option allows to disable image processing (useful for cost reduction).

agent.llm. disable_stop_word · boolean | null · default: false

Disable using of stop word.

agent.llm. caching_prompt · boolean · default: true

Enable caching of prompts.

agent.llm. log_completions · boolean · default: false

Enable logging of completions.

agent.llm. log_completions_folder · string · default: logs/completions

The folder to log LLM completions to. Required if log_completions is True.

agent.llm. custom_tokenizer · string | null

A custom tokenizer to use for token counting.

agent.llm. native_tool_calling · boolean · default: true

Whether to use native tool calling.

agent.llm. force_string_serializer · boolean | null

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.

agent.llm. reasoning_effort · enum<string> | null · default: high

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.

Available options: low, medium, high, none

agent.llm. reasoning_summary · enum<string> | null

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.

Available options: auto, concise, detailed

agent.llm. enable_encrypted_reasoning · boolean · default: false

If True, ask for ['reasoning.encrypted_content'] in Responses API include.

agent.llm. prompt_cache_retention · string | null · default: 24h

Retention policy for prompt cache. Only sent for GPT-5+ models; explicitly stripped for all other models.

agent.llm. extended_thinking_budget · integer | null · default: 200000

The budget tokens for extended thinking, supported by Anthropic models.

agent.llm. seed · integer | null

The seed to use for random number generation.

agent.llm. safety_settings · Safety Settings · object[] | null

Safety settings for models that support them (like Mistral AI and Gemini)

Show child attributes

agent.llm.safety_settings. {key} · string

agent.llm. usage_id · string · default: default

Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.

agent.llm. litellm_extra_body · Litellm Extra Body · object

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}

agent.llm. OVERRIDE_ON_SERIALIZE · string[]

agent. kind · string · default: Agent

Allowed value: "Agent"

agent. tools · Tool · object[]

List of tools to initialize for the agent.

Show child attributes

agent.tools. name · string · required

Name of the tool class, e.g., 'TerminalTool'. Import it from an openhands.tools.<module> subpackage.

agent.tools. params · Params · object

Parameters for the tool's .create() method, e.g., {'working_dir': '/app'}

agent. mcp_config · Mcp Config · object

Optional MCP configuration dictionary to create MCP tools.

agent. filter_tools_regex · string | null

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.*$"

agent. agent_context · AgentContext · object

Optional AgentContext to initialize the agent with specific context.

Show child attributes

agent.agent_context. skills · Skill · object[]

List of available skills that can extend the user's input.

Show child attributes

agent.agent_context.skills. name · string · required

agent.agent_context.skills. content · string · required

agent.agent_context.skills. trigger · KeywordTrigger · object

Skills use triggers to determine when they should be activated. None implies skill is always active. Other implementations include KeywordTrigger (activated by a keyword in a Message) and TaskTrigger (activated by specific tasks and may require user input)

KeywordTrigger

TaskTrigger

Show child attributes

agent.agent_context.skills.trigger. keywords · string[] · required

agent.agent_context.skills.trigger. type · string · default: keyword

Allowed value: "keyword"

agent.agent_context.skills. source · string | null

The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill.

agent.agent_context.skills. mcp_tools · Mcp Tools · object

MCP tools configuration for the skill (repo skills only). It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format

agent.agent_context.skills. inputs · InputMetadata · object[]

Input metadata for the skill (task skills only)

Show child attributes

agent.agent_context.skills.inputs. name · string · required

Name of the input parameter

agent.agent_context.skills.inputs. description · string · required

Description of the input parameter

agent.agent_context. system_message_suffix · string | null

Optional suffix to append to the system prompt.

agent.agent_context. user_message_suffix · string | null

Optional suffix to append to the user's message.

agent.agent_context. load_user_skills · boolean · default: false

Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility).

agent.agent_context. load_public_skills · boolean · default: false

Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/skills. This allows you to get the latest skills without SDK updates.

Example:

{
  "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'"
}

agent. system_prompt_filename · string · default: system_prompt.j2

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')

agent. system_prompt_kwargs · System Prompt Kwargs · object

Optional kwargs to pass to the system prompt Jinja2 template.

agent. condenser · LLMSummarizingCondenser · object

Optional condenser to use for condensing conversation history.

LLMSummarizingCondenser

NoOpCondenser

PipelineCondenser

Show child attributes

agent.condenser. llm · LLM · object · required

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.

Example: >>> 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

Show child attributes

agent.condenser.llm. model · string · default: claude-sonnet-4-20250514

Model name.

agent.condenser.llm. api_key

API key.

agent.condenser.llm. base_url · string | null

Custom base URL.

agent.condenser.llm. api_version · string | null

API version (e.g., Azure).

agent.condenser.llm. aws_access_key_id

agent.condenser.llm. aws_secret_access_key

agent.condenser.llm. aws_region_name · string | null

agent.condenser.llm. openrouter_site_url · string · default: https://docs.all-hands.dev/

agent.condenser.llm. openrouter_app_name · string · default: OpenHands

agent.condenser.llm. num_retries · integer · default: 5

Required range: x >= 0

agent.condenser.llm. retry_multiplier · number · default: 8

Required range: x >= 0

agent.condenser.llm. retry_min_wait · integer · default: 8

Required range: x >= 0

agent.condenser.llm. retry_max_wait · integer · default: 64

Required range: x >= 0

agent.condenser.llm. timeout · integer | null

HTTP timeout (s).

Required range: x >= 0

agent.condenser.llm. max_message_chars · integer · default: 30000

Approx max chars in each event/content sent to the LLM.

Required range: x >= 1

agent.condenser.llm. temperature · number | null

Sampling temperature for response generation. Defaults to 0 for most models and provider default for reasoning models.

Required range: x >= 0

agent.condenser.llm. top_p · number | null · default: 1

Required range: 0 <= x <= 1

agent.condenser.llm. top_k · number | null

Required range: x >= 0

agent.condenser.llm. custom_llm_provider · string | null

agent.condenser.llm. max_input_tokens · integer | null

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).

Required range: x >= 1

agent.condenser.llm. max_output_tokens · integer | null

The maximum number of output tokens. This is sent to the LLM.

Required range: x >= 1

agent.condenser.llm. extra_headers · Extra Headers · object

Optional HTTP headers to forward to LiteLLM requests.

Show child attributes

agent.condenser.llm.extra_headers. {key} · string

agent.condenser.llm. input_cost_per_token · number | null

The cost per input token. This will available in logs for user.

Required range: x >= 0

agent.condenser.llm. output_cost_per_token · number | null

The cost per output token. This will available in logs for user.

Required range: x >= 0

agent.condenser.llm. ollama_base_url · string | null

agent.condenser.llm. stream · boolean · default: false

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.

agent.condenser.llm. drop_params · boolean · default: true

agent.condenser.llm. modify_params · boolean · default: true

Modify params allows litellm to do transformations like adding a default message, when a message is empty.

agent.condenser.llm. disable_vision · boolean | null

If model is vision capable, this option allows to disable image processing (useful for cost reduction).

agent.condenser.llm. disable_stop_word · boolean | null · default: false

Disable using of stop word.

agent.condenser.llm. caching_prompt · boolean · default: true

Enable caching of prompts.

agent.condenser.llm. log_completions · boolean · default: false

Enable logging of completions.

agent.condenser.llm. log_completions_folder · string · default: logs/completions

The folder to log LLM completions to. Required if log_completions is True.

agent.condenser.llm. custom_tokenizer · string | null

A custom tokenizer to use for token counting.

agent.condenser.llm. native_tool_calling · boolean · default: true

Whether to use native tool calling.

agent.condenser.llm. force_string_serializer · boolean | null

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.

agent.condenser.llm. reasoning_effort · enum<string> | null · default: high

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.

Available options: low, medium, high, none

agent.condenser.llm. reasoning_summary · enum<string> | null

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.

Available options: auto, concise, detailed

agent.condenser.llm. enable_encrypted_reasoning · boolean · default: false

If True, ask for ['reasoning.encrypted_content'] in Responses API include.

agent.condenser.llm. prompt_cache_retention · string | null · default: 24h

Retention policy for prompt cache. Only sent for GPT-5+ models; explicitly stripped for all other models.

agent.condenser.llm. extended_thinking_budget · integer | null · default: 200000

The budget tokens for extended thinking, supported by Anthropic models.

agent.condenser.llm. seed · integer | null

The seed to use for random number generation.

agent.condenser.llm. safety_settings · Safety Settings · object[] | null

Safety settings for models that support them (like Mistral AI and Gemini)

Show child attributes

agent.condenser.llm.safety_settings. {key} · string

agent.condenser.llm. usage_id · string · default: default

Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.

agent.condenser.llm. litellm_extra_body · Litellm Extra Body · object

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}

agent.condenser.llm. OVERRIDE_ON_SERIALIZE · string[]

agent.condenser. kind · string · default: LLMSummarizingCondenser

Allowed value: "LLMSummarizingCondenser"

agent.condenser. max_size · integer · default: 120

agent.condenser. keep_first · integer · default: 4

Required range: x >= 0

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
}

workspace · LocalWorkspace · object · required

Working directory for agent operations and tool execution

Show child attributes

workspace. working_dir · string · required

The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings.

workspace. kind · string · default: LocalWorkspace

Allowed value: "LocalWorkspace"

conversation_id · string<uuid> | null

Optional conversation ID. If not provided, a random UUID will be generated.

confirmation_policy · AlwaysConfirm · object

Controls when the conversation will prompt the user before continuing. Defaults to never.

AlwaysConfirm

ConfirmRisky

NeverConfirm

Show child attributes

confirmation_policy. kind · string · default: AlwaysConfirm

Allowed value: "AlwaysConfirm"

initial_message · SendMessageRequest · object

Initial message to pass to the LLM

Show child attributes

initial_message. role · enum<string> · default: user

Available options: user, system, assistant, tool

initial_message. content · (TextContent · object | ImageContent · object)[]

TextContent

ImageContent

Show child attributes

initial_message.content. text · string · required

initial_message.content. cache_prompt · boolean · default: false

initial_message.content. type · string · default: text

Allowed value: "text"

initial_message. run · boolean · default: false

Whether the agent loop should automatically run if not running

max_iterations · integer · default: 500

If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops.

Required range: x >= 1

stuck_detection · boolean · default: true

If true, the conversation will use stuck detection to prevent infinite loops.

secrets · Secrets · object

Secrets available in the conversation

Show child attributes

secrets. {key} · LookupSecret · object

A secret looked up from some external url

LookupSecret

StaticSecret

Show child attributes

secrets.{key}. url · string · required

secrets.{key}. kind · string · default: LookupSecret

Allowed value: "LookupSecret"

secrets.{key}. description · string | null

Optional description for this secret

secrets.{key}. headers · Headers · object

Show child attributes

secrets.{key}.headers. {key} · string

Response

200

application/json

Successful Response

Information about a conversation running locally without a Runtime sandbox.

id · string<uuid> · required

Unique conversation ID

agent · Agent · object · required

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.

Show child attributes

agent. llm · LLM · object · required

LLM configuration for the agent.

Show child attributes

agent.llm. model · string · default: claude-sonnet-4-20250514

Model name.

agent.llm. api_key

API key.

agent.llm. base_url · string | null

Custom base URL.

agent.llm. api_version · string | null

API version (e.g., Azure).

agent.llm. aws_access_key_id

agent.llm. aws_secret_access_key

agent.llm. aws_region_name · string | null

agent.llm. openrouter_site_url · string · default: https://docs.all-hands.dev/

agent.llm. openrouter_app_name · string · default: OpenHands

agent.llm. num_retries · integer · default: 5

Required range: x >= 0

agent.llm. retry_multiplier · number · default: 8

Required range: x >= 0

agent.llm. retry_min_wait · integer · default: 8

Required range: x >= 0

agent.llm. retry_max_wait · integer · default: 64

Required range: x >= 0

agent.llm. timeout · integer | null

HTTP timeout (s).

Required range: x >= 0

agent.llm. max_message_chars · integer · default: 30000

Approx max chars in each event/content sent to the LLM.

Required range: x >= 1

agent.llm. temperature · number | null

Sampling temperature for response generation. Defaults to 0 for most models and provider default for reasoning models.

Required range: x >= 0

agent.llm. top_p · number | null · default: 1

Required range: 0 <= x <= 1

agent.llm. top_k · number | null

Required range: x >= 0

agent.llm. custom_llm_provider · string | null

agent.llm. max_input_tokens · integer | null

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).

Required range: x >= 1

agent.llm. max_output_tokens · integer | null

The maximum number of output tokens. This is sent to the LLM.

Required range: x >= 1

agent.llm. extra_headers · Extra Headers · object

Optional HTTP headers to forward to LiteLLM requests.

Show child attributes

agent.llm.extra_headers. {key} · string

agent.llm. input_cost_per_token · number | null

The cost per input token. This will available in logs for user.

Required range: x >= 0

agent.llm. output_cost_per_token · number | null

The cost per output token. This will available in logs for user.

Required range: x >= 0

agent.llm. ollama_base_url · string | null

agent.llm. stream · boolean · default: false

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.

agent.llm. drop_params · boolean · default: true

agent.llm. modify_params · boolean · default: true

Modify params allows litellm to do transformations like adding a default message, when a message is empty.

agent.llm. disable_vision · boolean | null

If model is vision capable, this option allows to disable image processing (useful for cost reduction).

agent.llm. disable_stop_word · boolean | null · default: false

Disable using of stop word.

agent.llm. caching_prompt · boolean · default: true

Enable caching of prompts.

agent.llm. log_completions · boolean · default: false

Enable logging of completions.

agent.llm. log_completions_folder · string · default: logs/completions

The folder to log LLM completions to. Required if log_completions is True.

agent.llm. custom_tokenizer · string | null

A custom tokenizer to use for token counting.

agent.llm. native_tool_calling · boolean · default: true

Whether to use native tool calling.

agent.llm. force_string_serializer · boolean | null

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.

agent.llm. reasoning_effort · enum<string> | null · default: high

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.

Available options: low, medium, high, none

agent.llm. reasoning_summary · enum<string> | null

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.

Available options: auto, concise, detailed

agent.llm. enable_encrypted_reasoning · boolean · default: false

If True, ask for ['reasoning.encrypted_content'] in Responses API include.

agent.llm. prompt_cache_retention · string | null · default: 24h

Retention policy for prompt cache. Only sent for GPT-5+ models; explicitly stripped for all other models.

agent.llm. extended_thinking_budget · integer | null · default: 200000

The budget tokens for extended thinking, supported by Anthropic models.

agent.llm. seed · integer | null

The seed to use for random number generation.

agent.llm. safety_settings · Safety Settings · object[] | null

Safety settings for models that support them (like Mistral AI and Gemini)

Show child attributes

agent.llm.safety_settings. {key} · string

agent.llm. usage_id · string · default: default

Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.

agent.llm. litellm_extra_body · Litellm Extra Body · object

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}

agent.llm. OVERRIDE_ON_SERIALIZE · string[]

agent. kind · string · default: Agent

Allowed value: "Agent"

agent. tools · Tool · object[]

List of tools to initialize for the agent.

Show child attributes

agent.tools. name · string · required

Name of the tool class, e.g., 'TerminalTool'. Import it from an openhands.tools.<module> subpackage.

agent.tools. params · Params · object

Parameters for the tool's .create() method, e.g., {'working_dir': '/app'}

agent. mcp_config · Mcp Config · object

Optional MCP configuration dictionary to create MCP tools.

agent. filter_tools_regex · string | null

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.*$"

agent. agent_context · AgentContext · object

Optional AgentContext to initialize the agent with specific context.

Show child attributes

agent.agent_context. skills · Skill · object[]

List of available skills that can extend the user's input.

Show child attributes

agent.agent_context.skills. name · string · required

agent.agent_context.skills. content · string · required

agent.agent_context.skills. trigger · KeywordTrigger · object

Skills use triggers to determine when they should be activated. None implies skill is always active. Other implementations include KeywordTrigger (activated by a keyword in a Message) and TaskTrigger (activated by specific tasks and may require user input)

KeywordTrigger

TaskTrigger

Show child attributes

agent.agent_context.skills.trigger. keywords · string[] · required

agent.agent_context.skills.trigger. type · string · default: keyword

Allowed value: "keyword"

agent.agent_context.skills. source · string | null

The source path or identifier of the skill. When it is None, it is treated as a programmatically defined skill.

agent.agent_context.skills. mcp_tools · Mcp Tools · object

MCP tools configuration for the skill (repo skills only). It should conform to the MCPConfig schema: https://gofastmcp.com/clients/client#configuration-format

agent.agent_context.skills. inputs · InputMetadata · object[]

Input metadata for the skill (task skills only)

Show child attributes

agent.agent_context.skills.inputs. name · string · required

Name of the input parameter

agent.agent_context.skills.inputs. description · string · required

Description of the input parameter

agent.agent_context. system_message_suffix · string | null

Optional suffix to append to the system prompt.

agent.agent_context. user_message_suffix · string | null

Optional suffix to append to the user's message.

agent.agent_context. load_user_skills · boolean · default: false

Whether to automatically load user skills from ~/.openhands/skills/ and ~/.openhands/microagents/ (for backward compatibility).

agent.agent_context. load_public_skills · boolean · default: false

Whether to automatically load skills from the public OpenHands skills repository at https://github.com/OpenHands/skills. This allows you to get the latest skills without SDK updates.

Example:

{
  "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'"
}

agent. system_prompt_filename · string · default: system_prompt.j2

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')

agent. system_prompt_kwargs · System Prompt Kwargs · object

Optional kwargs to pass to the system prompt Jinja2 template.

agent. condenser · LLMSummarizingCondenser · object

Optional condenser to use for condensing conversation history.

LLMSummarizingCondenser

NoOpCondenser

PipelineCondenser

Show child attributes

agent.condenser. llm · LLM · object · required

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.

Example: >>> 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

Show child attributes

agent.condenser.llm. model · string · default: claude-sonnet-4-20250514

Model name.

agent.condenser.llm. api_key

API key.

agent.condenser.llm. base_url · string | null

Custom base URL.

agent.condenser.llm. api_version · string | null

API version (e.g., Azure).

agent.condenser.llm. aws_access_key_id

agent.condenser.llm. aws_secret_access_key

agent.condenser.llm. aws_region_name · string | null

agent.condenser.llm. openrouter_site_url · string · default: https://docs.all-hands.dev/

agent.condenser.llm. openrouter_app_name · string · default: OpenHands

agent.condenser.llm. num_retries · integer · default: 5

Required range: x >= 0

agent.condenser.llm. retry_multiplier · number · default: 8

Required range: x >= 0

agent.condenser.llm. retry_min_wait · integer · default: 8

Required range: x >= 0

agent.condenser.llm. retry_max_wait · integer · default: 64

Required range: x >= 0

agent.condenser.llm. timeout · integer | null

HTTP timeout (s).

Required range: x >= 0

agent.condenser.llm. max_message_chars · integer · default: 30000

Approx max chars in each event/content sent to the LLM.

Required range: x >= 1

agent.condenser.llm. temperature · number | null

Sampling temperature for response generation. Defaults to 0 for most models and provider default for reasoning models.

Required range: x >= 0

agent.condenser.llm. top_p · number | null · default: 1

Required range: 0 <= x <= 1

agent.condenser.llm. top_k · number | null

Required range: x >= 0

agent.condenser.llm. custom_llm_provider · string | null

agent.condenser.llm. max_input_tokens · integer | null

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).

Required range: x >= 1

agent.condenser.llm. max_output_tokens · integer | null

The maximum number of output tokens. This is sent to the LLM.

Required range: x >= 1

agent.condenser.llm. extra_headers · Extra Headers · object

Optional HTTP headers to forward to LiteLLM requests.

Show child attributes

agent.condenser.llm.extra_headers. {key} · string

agent.condenser.llm. input_cost_per_token · number | null

The cost per input token. This will available in logs for user.

Required range: x >= 0

agent.condenser.llm. output_cost_per_token · number | null

The cost per output token. This will available in logs for user.

Required range: x >= 0

agent.condenser.llm. ollama_base_url · string | null

agent.condenser.llm. stream · boolean · default: false

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.

agent.condenser.llm. drop_params · boolean · default: true

agent.condenser.llm. modify_params · boolean · default: true

Modify params allows litellm to do transformations like adding a default message, when a message is empty.

agent.condenser.llm. disable_vision · boolean | null

If model is vision capable, this option allows to disable image processing (useful for cost reduction).

agent.condenser.llm. disable_stop_word · boolean | null · default: false

Disable using of stop word.

agent.condenser.llm. caching_prompt · boolean · default: true

Enable caching of prompts.

agent.condenser.llm. log_completions · boolean · default: false

Enable logging of completions.

agent.condenser.llm. log_completions_folder · string · default: logs/completions

The folder to log LLM completions to. Required if log_completions is True.

agent.condenser.llm. custom_tokenizer · string | null

A custom tokenizer to use for token counting.

agent.condenser.llm. native_tool_calling · boolean · default: true

Whether to use native tool calling.

agent.condenser.llm. force_string_serializer · boolean | null

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.

agent.condenser.llm. reasoning_effort · enum<string> | null · default: high

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.

Available options: low, medium, high, none

agent.condenser.llm. reasoning_summary · enum<string> | null

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.

Available options: auto, concise, detailed

agent.condenser.llm. enable_encrypted_reasoning · boolean · default: false

If True, ask for ['reasoning.encrypted_content'] in Responses API include.

agent.condenser.llm. prompt_cache_retention · string | null · default: 24h

Retention policy for prompt cache. Only sent for GPT-5+ models; explicitly stripped for all other models.

agent.condenser.llm. extended_thinking_budget · integer | null · default: 200000

The budget tokens for extended thinking, supported by Anthropic models.

agent.condenser.llm. seed · integer | null

The seed to use for random number generation.

agent.condenser.llm. safety_settings · Safety Settings · object[] | null

Safety settings for models that support them (like Mistral AI and Gemini)

Show child attributes

agent.condenser.llm.safety_settings. {key} · string

agent.condenser.llm. usage_id · string · default: default

Unique usage identifier for the LLM. Used for registry lookups, telemetry, and spend tracking.

agent.condenser.llm. litellm_extra_body · Litellm Extra Body · object

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}

agent.condenser.llm. OVERRIDE_ON_SERIALIZE · string[]

agent.condenser. kind · string · default: LLMSummarizingCondenser

Allowed value: "LLMSummarizingCondenser"

agent.condenser. max_size · integer · default: 120

agent.condenser. keep_first · integer · default: 4

Required range: x >= 0

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
}

workspace · LocalWorkspace · object · required

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

RemoteWorkspace

Show child attributes

workspace. working_dir · string · required

The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings.

workspace. kind · string · default: LocalWorkspace

Allowed value: "LocalWorkspace"

persistence_dir · string | null · default: workspace/conversations

Directory for persisting conversation state and events. If None, conversation will not be persisted.

max_iterations · integer · default: 500

Maximum number of iterations the agent can perform in a single run.

stuck_detection · boolean · default: true

Whether to enable stuck detection for the agent.

execution_status · enum<string> · default: idle

Enum representing the current execution state of the conversation.

Available options: idle, running, paused, waiting_for_confirmation, finished, error, stuck

confirmation_policy · AlwaysConfirm · object

AlwaysConfirm

ConfirmRisky

NeverConfirm

Show child attributes

confirmation_policy. kind · string · default: AlwaysConfirm

Allowed value: "AlwaysConfirm"

security_analyzer · LLMSecurityAnalyzer · object

Optional security analyzer to evaluate action risks.

Show child attributes

security_analyzer. kind · string · default: LLMSecurityAnalyzer

Allowed value: "LLMSecurityAnalyzer"

activated_knowledge_skills · string[]

List of activated knowledge skills name

stats · ConversationStats · object

Conversation statistics for tracking LLM metrics

Show child attributes

stats. usage_to_metrics · Usage To Metrics · object

Active usage metrics tracked by the registry.

Show child attributes

stats.usage_to_metrics. {key} · Metrics · object

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).

Show child attributes

stats.usage_to_metrics.{key}. model_name · string · default: default

Name of the model

stats.usage_to_metrics.{key}. accumulated_cost · number · default: 0

Total accumulated cost, must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}. max_budget_per_task · number | null

Maximum budget per task

stats.usage_to_metrics.{key}. accumulated_token_usage · TokenUsage · object

Accumulated token usage across all calls

Show child attributes

stats.usage_to_metrics.{key}.accumulated_token_usage. model · string · default: ""

stats.usage_to_metrics.{key}.accumulated_token_usage. prompt_tokens · integer · default: 0

Prompt tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. completion_tokens · integer · default: 0

Completion tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. cache_read_tokens · integer · default: 0

Cache read tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. cache_write_tokens · integer · default: 0

Cache write tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. reasoning_tokens · integer · default: 0

Reasoning tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. context_window · integer · default: 0

Context window must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. per_turn_token · integer · default: 0

Per turn tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.accumulated_token_usage. response_id · string · default: ""

stats.usage_to_metrics.{key}. costs · Cost · object[]

List of individual costs

Show child attributes

stats.usage_to_metrics.{key}.costs. model · string · required

stats.usage_to_metrics.{key}.costs. cost · number · required

Cost must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.costs. timestamp · number

stats.usage_to_metrics.{key}. response_latencies · ResponseLatency · object[]

List of response latencies

Show child attributes

stats.usage_to_metrics.{key}.response_latencies. model · string · required

stats.usage_to_metrics.{key}.response_latencies. latency · number · required

Latency must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.response_latencies. response_id · string · required

stats.usage_to_metrics.{key}. token_usages · TokenUsage · object[]

List of token usage records

Show child attributes

stats.usage_to_metrics.{key}.token_usages. model · string · default: ""

stats.usage_to_metrics.{key}.token_usages. prompt_tokens · integer · default: 0

Prompt tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. completion_tokens · integer · default: 0

Completion tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. cache_read_tokens · integer · default: 0

Cache read tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. cache_write_tokens · integer · default: 0

Cache write tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. reasoning_tokens · integer · default: 0

Reasoning tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. context_window · integer · default: 0

Context window must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. per_turn_token · integer · default: 0

Per turn tokens must be non-negative

Required range: x >= 0

stats.usage_to_metrics.{key}.token_usages. response_id · string · default: ""

secret_registry · SecretRegistry · object

Registry for handling secrets and sensitive data

Show child attributes

secret_registry. secret_sources · Secret Sources · object

Show child attributes

secret_registry.secret_sources. {key} · LookupSecret · object

A secret looked up from some external url

LookupSecret

StaticSecret

Show child attributes

secret_registry.secret_sources.{key}. url · string · required

secret_registry.secret_sources.{key}. kind · string · default: LookupSecret

Allowed value: "LookupSecret"

secret_registry.secret_sources.{key}. description · string | null

Optional description for this secret

secret_registry.secret_sources.{key}. headers · Headers · object

Show child attributes

secret_registry.secret_sources.{key}.headers. {key} · string

title · string | null

User-defined title for the conversation

metrics · MetricsSnapshot · object

A snapshot of metrics at a point in time.

Does not include lists of individual costs, latencies, or token usages.

Show child attributes

metrics. model_name · string · default: default

Name of the model

metrics. accumulated_cost · number · default: 0

Total accumulated cost, must be non-negative

Required range: x >= 0

metrics. max_budget_per_task · number | null

Maximum budget per task

metrics. accumulated_token_usage · TokenUsage · object

Accumulated token usage across all calls

Show child attributes

metrics.accumulated_token_usage. model · string · default: ""

metrics.accumulated_token_usage. prompt_tokens · integer · default: 0

Prompt tokens must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. completion_tokens · integer · default: 0

Completion tokens must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. cache_read_tokens · integer · default: 0

Cache read tokens must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. cache_write_tokens · integer · default: 0

Cache write tokens must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. reasoning_tokens · integer · default: 0

Reasoning tokens must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. context_window · integer · default: 0

Context window must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. per_turn_token · integer · default: 0

Per turn tokens must be non-negative

Required range: x >= 0

metrics.accumulated_token_usage. response_id · string · default: ""

created_at · string<date-time>

updated_at · string<date-time>