Skip to main content
POST
On Conversation Update

Authorizations

X-Access-Token
string
header
required

Body

application/json

Information about a conversation running locally without a Runtime sandbox.

id
string<uuid>
required

Unique conversation ID

workspace
LocalWorkspace · object
required

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

agent
ACPAgent · object
required

The agent running in the conversation.

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
security_analyzer
PatternSecurityAnalyzer · object

Optional security analyzer to evaluate action risks.

activated_knowledge_skills
string[]

List of activated knowledge skills name

invoked_skills
string[]

Names of progressive-disclosure skills explicitly invoked via the invoke_skill tool.

blocked_actions
Blocked Actions · object

Actions blocked by PreToolUse hooks, keyed by action ID

blocked_messages
Blocked Messages · object

Messages blocked by UserPromptSubmit hooks, keyed by message ID

last_user_message_id
string | null

Most recent user MessageEvent id for hook block checks. Updated when user messages are emitted so Agent.step can pop blocked_messages without scanning the event log. If None, hook-blocked checks are skipped (legacy conversations).

leaf_event_id
string | null

HEAD of the conversation tree: the parent of the next appended event. None means an empty tree (or, for pre-feature conversations, the linear tail). Moving it via navigate re-roots the active branch the agent runs on.

stats
ConversationStats · object

Conversation statistics for tracking LLM metrics

secret_registry
SecretRegistry · object

Registry for handling secrets and sensitive data

agent_state
Agent State · object

Dictionary for agent-specific runtime state that persists across iterations.

hook_config
HookConfig · object | null

Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks.

title
string | null

User-defined title for the conversation

metrics
MetricsSnapshot · 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>
forked_from_conversation_id
string<uuid> | null

ID of the conversation this one was forked from. None for conversations created directly (not via fork).

forked_from_event_id
string | null

Event ID this conversation was forked at. None for non-forked conversations or whole-conversation forks.

parent_conversation_id
string<uuid> | null

ID of the conversation that owns this one. None for top-level conversations.

sub_conversation_ids
string<uuid>[]

IDs of conversations naming this one as their parent. Derived from the server catalog; empty on webhook payloads. Name mirrors the Cloud API field.

tags
Tags · object

Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters.

current_model_id
string | null

Model the agent is actually using for this session. For ACP agents, this is lifted off ACPAgent.current_model_id (populated from the models.currentModelId field on the ACP session response, or from acp_model when the caller forced an override). May be an opaque alias (e.g. claude-agent-acp's "default"); match it against available_models to get a display label. None for older ACP servers that don't surface the field, or while the agent is still initializing. Native OpenHands agents leave this None — consumers should read agent.llm.model for those.

available_models
ACPModelInfo · object[]

Models the ACP server offers for this session, lifted off ACPAgent.available_models (the models.availableModels field on the ACP session response). Each entry carries a model_id plus an optional name/description. Surfaced verbatim so clients can render a model picker and resolve current_model_id to a display label themselves — the server does no name curation. Empty for ACP servers that don't surface the (UNSTABLE) capability and for native OpenHands agents. Client contract: current_model_id is NOT guaranteed to be a member — a forced acp_model override may name a model absent from the list — so treat a miss as 'show the raw id'. Some entries are opaque aliases whose human identity lives in description (e.g. claude-agent-acp's "default" -> "Opus 4.7 with 1M context · ...").

supports_runtime_model_switch
boolean
default:false

Whether a live, mid-conversation model switch will be attempted for this conversation — tells the inline picker whether to offer a live-switch control. Mirrors the SDK's switch gate: True for known switch-capable providers; False for unknown/custom ACP servers because their generic config writes are not guaranteed live-switch primitives. False for native OpenHands agents, for a known provider that declares no support, and before the conversation has started a session.

launched_agent_profile
LaunchedAgentProfile · object | null

Provenance snapshot of the agent profile that launched this conversation. Set at creation when the conversation was started via agent_profile_id; None for conversations started directly with agent or agent_settings. Clients use this to identify which agent profile is current without fragile settings-comparison.

client_tools
ClientToolSpec · object[]

Client-defined tool specs registered for this conversation. Surfaced so that a client re-attaching by conversation id can register the dynamic ClientAction_* action types before syncing persisted events, avoiding 'Unknown kind' deserialization errors.

Response

Successful Response

success
boolean
default:true