Start Conversation

Start a conversation in the local environment.

POST /api/conversations

Start Conversation

cURL

curl --request POST \
  --url https://api.example.com/api/conversations \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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": 300,
      "max_message_chars": 30000,
      "temperature": 1,
      "top_p": 1,
      "top_k": 1,
      "max_input_tokens": 2,
      "max_output_tokens": 2,
      "model_canonical_name": "<string>",
      "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": true,
      "prompt_cache_retention": "24h",
      "extended_thinking_budget": 200000,
      "seed": 123,
      "safety_settings": [
        {}
      ],
      "usage_id": "default",
      "litellm_extra_body": {}
    },
    "tools": [
      {
        "name": "<string>",
        "params": {}
      }
    ],
    "mcp_config": {},
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "include_default_tools": [
      "<string>"
    ],
    "agent_context": {
      "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_filename": "system_prompt.j2",
    "security_policy_filename": "security_policy.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
    },
    "critic": {
      "kind": "AgentFinishedCritic"
    },
    "kind": "<string>"
  },
  "workspace": {
    "working_dir": "<string>",
    "kind": "<string>"
  },
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "initial_message": {
    "role": "user",
    "content": [
      {
        "text": "<string>",
        "cache_prompt": false,
        "type": "text"
      }
    ],
    "run": false
  },
  "max_iterations": 500,
  "stuck_detection": true,
  "secrets": {},
  "tool_module_qualnames": {},
  "plugins": [
    {
      "source": "<string>",
      "ref": "<string>",
      "repo_path": "<string>"
    }
  ],
  "hook_config": {
    "pre_tool_use": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60
          }
        ]
      }
    ],
    "post_tool_use": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60
          }
        ]
      }
    ],
    "user_prompt_submit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60
          }
        ]
      }
    ],
    "session_start": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60
          }
        ]
      }
    ],
    "session_end": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60
          }
        ]
      }
    ],
    "stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
EOF

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": 300,
      "max_message_chars": 30000,
      "temperature": 1,
      "top_p": 1,
      "top_k": 1,
      "max_input_tokens": 2,
      "max_output_tokens": 2,
      "model_canonical_name": "<string>",
      "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": true,
      "prompt_cache_retention": "24h",
      "extended_thinking_budget": 200000,
      "seed": 123,
      "safety_settings": [
        {}
      ],
      "usage_id": "default",
      "litellm_extra_body": {}
    },
    "kind": "<string>",
    "tools": [
      {
        "name": "<string>",
        "params": {}
      }
    ],
    "mcp_config": {},
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "include_default_tools": [
      "<string>"
    ],
    "agent_context": {
      "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_filename": "system_prompt.j2",
    "security_policy_filename": "security_policy.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
    },
    "critic": {
      "kind": "AgentFinishedCritic"
    }
  },
  "workspace": {
    "working_dir": "<string>",
    "kind": "<string>"
  },
  "persistence_dir": "workspace/conversations",
  "max_iterations": 500,
  "stuck_detection": true,
  "execution_status": "idle",
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "security_analyzer": {
    "kind": "<string>"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "blocked_actions": {},
  "blocked_messages": {},
  "stats": {},
  "secret_registry": {
    "secret_sources": {}
  },
  "agent_state": {},
  "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. Critic-related functionality is provided by CriticMixin.

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

workspace · LocalWorkspace · object · required

Working directory for agent operations and tool execution

Show child attributes

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

initial_message · SendMessageRequest · object

Initial message to pass to the LLM

Show child attributes

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

tool_module_qualnames · Tool Module Qualnames · object

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.

Show child attributes

plugins · PluginSource · object[] | null

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.

Show child attributes

hook_config · HookConfig · object

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.

Show child attributes

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

workspace · LocalWorkspace · object · required

Workspace used by the agent to execute commands and read/write files. Not the process working directory.

LocalWorkspace

RemoteWorkspace

Show child attributes

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, deleting

confirmation_policy · AlwaysConfirm · object

AlwaysConfirm

ConfirmRisky

NeverConfirm

Show child attributes

security_analyzer · LLMSecurityAnalyzer · object

Optional security analyzer to evaluate action risks.

Show child attributes

activated_knowledge_skills · string[]

List of activated knowledge skills name

blocked_actions · Blocked Actions · object

Actions blocked by PreToolUse hooks, keyed by action ID

Show child attributes

blocked_messages · Blocked Messages · object

Messages blocked by UserPromptSubmit hooks, keyed by message ID

Show child attributes

stats · object

Conversation statistics for tracking LLM metrics

secret_registry · SecretRegistry · object

Registry for handling secrets and sensitive data

Show child attributes

agent_state · Agent State · object

Dictionary for agent-specific runtime state that persists across iterations. Agents can store feature-specific state using string keys. To trigger autosave, always reassign: state.agent_state = {**state.agent_state, key: value}. See https://docs.openhands.dev/sdk/guides/convo-persistence#how-state-persistence-works

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

created_at · string<date-time>

updated_at · string<date-time>