Start Conversation

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "kind": "Agent",
    "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"
    },
    "tools": {
      "name": "BashTool",
      "params": {}
    },
    "mcp_config": {
      "mcpServers": {
        "fetch": {
          "args": [
            "mcp-server-fetch"
          ],
          "command": "uvx"
        }
      }
    },
    "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": {
      "cli_mode": true
    },
    "security_analyzer": {
      "kind": "LLMSecurityAnalyzer"
    },
    "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": {
    "kind": "LocalWorkspace",
    "working_dir": "<string>"
  },
  "persistence_dir": "<string>",
  "max_iterations": 500,
  "stuck_detection": true,
  "execution_status": "idle",
  "confirmation_policy": {
    "kind": "AlwaysConfirm"
  },
  "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": "<string>",
      "prompt_tokens": 1,
      "completion_tokens": 1,
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "reasoning_tokens": 1,
      "context_window": 1,
      "per_turn_token": 1,
      "response_id": "<string>"
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

POST

api

conversations

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "kind": "Agent",
    "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"
    },
    "tools": {
      "name": "BashTool",
      "params": {}
    },
    "mcp_config": {
      "mcpServers": {
        "fetch": {
          "args": [
            "mcp-server-fetch"
          ],
          "command": "uvx"
        }
      }
    },
    "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": {
      "cli_mode": true
    },
    "security_analyzer": {
      "kind": "LLMSecurityAnalyzer"
    },
    "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": {
    "kind": "LocalWorkspace",
    "working_dir": "<string>"
  },
  "persistence_dir": "<string>",
  "max_iterations": 500,
  "stuck_detection": true,
  "execution_status": "idle",
  "confirmation_policy": {
    "kind": "AlwaysConfirm"
  },
  "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": "<string>",
      "prompt_tokens": 1,
      "completion_tokens": 1,
      "cache_read_tokens": 1,
      "cache_write_tokens": 1,
      "reasoning_tokens": 1,
      "context_window": 1,
      "per_turn_token": 1,
      "response_id": "<string>"
    }
  },
  "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

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="BashTool"), Tool(name="FileEditorTool")] >>> agent = Agent(llm=llm, tools=tools)

Show child attributes

workspace

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

object

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

AlwaysConfirm
ConfirmRisky
NeverConfirm

Show child attributes

initial_message

object | null

Initial message to pass to the LLM Payload to send a message to the agent.

This is a simplified version of openhands.sdk.Message.

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

object

Secrets available in the conversation

Show child attributes

Response

Successful Response

Information about a conversation running locally without a Runtime sandbox.

string<uuid>

required

Unique conversation ID

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

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

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.

Required range: x > 0

stuck_detection

boolean

default:true

Whether to enable stuck detection for the agent.

execution_status

enum<string>

Enum representing the current execution state of the conversation.

Available options:

idle,

running,

paused,

waiting_for_confirmation,

finished,

error,

stuck

confirmation_policy

object

AlwaysConfirm
ConfirmRisky
NeverConfirm

Show child attributes

activated_knowledge_skills

string[]

List of activated knowledge skills name

stats

object

Conversation statistics for tracking LLM metrics

Show child attributes

secret_registry

object

Registry for handling secrets and sensitive data

Show child attributes

title

string | null

User-defined title for the conversation

metrics

object | null

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>

Batch Get Conversations Pause Conversation

⌘I

Guides

Architecture

API Reference

Body

Response