Skip to main content
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,
  "agent_status": "idle",
  "confirmation_policy": {
    "kind": "AlwaysConfirm"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "stats": {
    "usage_to_metrics": {}
  },
  "secrets_manager": {
    "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
workspace
object
required

Working directory for agent operations and tool execution

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

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

Response

Successful Response

Information about a conversation running locally without a Runtime sandbox.

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

workspace
object
required

Mixin providing local workspace operations.

  • LocalWorkspace
  • RemoteWorkspace
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.

agent_status
enum<string>

Enum representing the current execution state of the agent.

Available options:
idle,
running,
paused,
waiting_for_confirmation,
finished,
error,
stuck
confirmation_policy
object
  • AlwaysConfirm
  • ConfirmRisky
  • NeverConfirm
activated_knowledge_skills
string[]

List of activated knowledge skills name

stats
object

Conversation statistics for tracking LLM metrics

secrets_manager
object

Manager for handling secrets and sensitive data

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.

created_at
string<date-time>
updated_at
string<date-time>