Agents API

Agent endpoints cover lifecycle control, execution dispatch, telemetry, and diagnostics.

Common endpoints

GET /api/agents list agents in org scope
POST /api/agents/{id}/run execute saved script
POST /api/agents/{id}/builder/run execute a builder phase snippet on the worker
POST /api/agents/{id}/run-snippet execute an ad-hoc Python snippet on the worker
POST /api/agents/{id}/run-function execute a reusable function
POST /api/agents/{id}/script push or fetch script payloads
POST /api/agents/{id}/step-status callback for step-level progress
POST /api/agents/{id}/video-analyze create workflow from recording
GET /api/agents/{id}/status fetch lightweight live status for UI polling
GET /api/agents/{id}/runs fetch the 20 most recent runs with aggregated AI cost
GET /api/agents/{id}/run-snippet/status?commandId=... poll ad-hoc snippet execution status/results
POST /api/agents/{id}/dexis-images convert DEXIS .dex images to JPEG assets on the worker and upload to S3
GET /api/agents/{id}/dexis-images/status?commandId=... poll DEXIS conversion status/results
POST /api/agents/{id}/dexis-composite generate a labeled multi-tooth composite PNG from DEXIS images
GET /api/agents/{id}/dexis-composite/status?commandId=... poll DEXIS composite status/results
POST /api/agent/{id}/activity mark user workspace activity for idle-stop accounting

Lifecycle and VM state

POST /api/agent/{id}/action perform lifecycle and control actions.

Supported action values:

start
stop
reboot
terminate
repair (requires apiKey in body)
stop_job
start_job
start_recording
attach_recording
stop_recording
deploy_extension

Agent pool UI behavior for /app/agents:

start and stop are first-class table actions for operators.
rename is handled as a form action on /app/agents (not through POST /api/agent/{id}/action).
start restores publicTunnelUrl from the latest known tunnel hostname (publicTunnelUrl fallback to tunnelUrl) so Open View links recover immediately after boot.

start_job now performs JIT wake with unified policy enforcement:

If the target agent is stopped and org VM setting vmAutoWakeOnJob is enabled, Mimic starts the agent and waits up to 2 minutes for online.
If auto-wake is disabled, the endpoint returns 409 with a start-manually message.
The same auto-wake policy is enforced across manual dispatch, scheduled runs, and retry attempts.
Each wake attempt emits lifecycle events (wake_requested, wake_ready/wake_timeout/wake_failed, or wake_blocked).

reboot action behavior:

API returns after the reboot command is issued.
Agent status is set to rebooting immediately.
Clients should poll GET /api/agents/{id}/status until the agent returns to a stable state.

Polling endpoints for Agent View

Use these endpoints for high-frequency UI updates without re-running heavy page loaders.

`GET /api/agents/{id}/status`

Returns current persisted agent state and best-effort VM state (3-second timeout guard).

Response shape:

{
  "status": "online",
  "lastSeen": "2026-03-04T12:01:22.000Z",
  "lastActivityAt": "2026-03-04T12:00:10.000Z",
  "publicTunnelUrl": "https://...",
  "vmState": "running",
  "vmIp": "10.0.4.13"
}

`GET /api/agents/{id}/runs`

Returns up to 20 recent job-backed runs for one agent.

Response shape:

{
  "runs": [
    {
      "id": "job_uuid",
      "status": "success",
      "startedAt": "2026-03-04T11:40:00.000Z",
      "duration": 242000,
      "totalCost": 0.11,
      "totalSteps": 24,
      "passedSteps": 24,
      "failedSteps": 0,
      "error": null
    }
  ]
}

Idle management

PATCH /api/agent/{id}/idle-exempt

Request body:

{
  "exempt": true
}

Response:

{
  "success": true,
  "idleAutoStopExempt": true
}

Use this to pin an agent as always-on when org-level auto-stop is enabled.

Builder run endpoint

POST /api/agents/{id}/builder/run supports builder-phase execution for portal scripts.

Body fields:

phase required phase name
portal defaults to dentrix
mimicBaseUrl optional override for callback routing (for example local tunnel testing)
workflowPackId, workflowPackVersionId, workflowPackInstallationId optional release-context IDs
runtimeBundleId, runtimeBundleManifestKey optional deployed bundle lineage IDs

Runtime behavior:

Resolves the effective Mimic base URL from mimicBaseUrl override or PUBLIC_APP_URL.
Loads the target agent organization and injects org API credentials into worker env.
Injects MIMIC_BASE_URL, MIMIC_API_KEY, AGENT_ID, ORGANIZATION_ID, and workflow-pack lineage env vars before script execution.
Creates an isolated session run root on the VM and snapshots source files for reproducible builder runs.

This keeps dashboard callback and run-summary publish paths bound to the correct org context.

Ad-hoc snippet endpoints

Use these endpoints when Agent View needs deterministic worker-side diagnostics that are not modeled as a dedicated API action.

`POST /api/agents/{id}/run-snippet`

Request body:

{
  "code": "print('hello from worker')"
}

Behavior:

Starts a Python snippet on the target worker through VM command execution.
Returns immediately with { "commandId": "..." }.
Leaves completion tracking to the paired status endpoint.

`GET /api/agents/{id}/run-snippet/status?commandId=...`

Behavior:

Polls worker command status for the snippet run.
Returns { "status": "pending" | "success" | "failed", "output"?, "error"? }.
Used by Agent View SQL/DEXIS diagnostics flows that require long-running data collection.

Claim workflow endpoint usage

Agent View Claim Workflow (non-standard attachment readiness) does not introduce new API contracts. It composes existing endpoints:

POST /api/agents/{id}/run-snippet plus GET /api/agents/{id}/run-snippet/status for Scope and Gather phases.
The same run-snippet pair is used for current MVP execution steps after Review approval (attach_xray, write_narrative, import_perio, populate_prosthesis).
POST /api/agents/{id}/dexis-composite plus GET /api/agents/{id}/dexis-composite/status for optional composite generation in Gather/Review.
Current Agent View Claim Workflow submits patientLookup as String(selectedPatient.patimageid) when requesting composites.

Output handling requirements:

Parse snippet output using explicit markers (for example __CW_SCOPE_START__...__CW_SCOPE_END__) before JSON decode.
Parse execution payloads from __CW_EXEC_START__...__CW_EXEC_END__ before evaluating step success/failure.
Treat missing markers or invalid JSON as failed deterministic diagnostics and surface operator-visible errors.

DEXIS image conversion endpoints

Use these endpoints from Agent View DEXIS tooling to create browser-viewable previews from DEXIS flat-file images.

`POST /api/agents/{id}/dexis-images`

Request body:

{
  "dexisPath": "\\\\wmeis01\\DEXIS\\DATA\\1\\0\\0\\1\\0\\7\\4\\8",
  "patimageid": 10010748,
  "images": [{ "ordinal": 1, "filename": "000001.dex" }]
}

Behavior:

Runs a Python snippet on the target worker.
Reads .dex files (TIFF), including files with prefixed headers.
Generates thumbnail and full-size JPEG variants.
Uploads assets under dexis/{PATIMAGEID}/... in the configured bucket.
Returns { "commandId": "..." } for polling.

`GET /api/agents/{id}/dexis-images/status?commandId=...`

Behavior:

Polls VMService.getSnippetStatus for the command.
Returns snippet status and output payload.
Mirrors the same polling model used by run-snippet/status.

DEXIS tooth composite endpoints

Use these endpoints from Agent View DEXIS tooling to build one labeled image across multiple requested teeth.

`POST /api/agents/{id}/dexis-composite`

Request body:

{
  "patientLookup": "10010748",
  "teeth": [18, 31]
}

patientLookup accepts patient name, chart number, PATIMAGEID, or display labels that include PATIMAGEID.

Behavior:

Runs a Python snippet on the target worker.
Resolves the patient in Dentrix SQL (DDB_PAT) using the lookup value.
Parses DEXIS.dat, decodes tooth data from field [10] (FDI -> ADA), and selects the most recent image per requested tooth.
Builds a labeled PNG composite with placeholders for missing teeth.
Uploads the composite under dexis/comp/... in the configured bucket.
Returns { "commandId": "..." } for polling.

`GET /api/agents/{id}/dexis-composite/status?commandId=...`

Behavior:

Polls VMService.getSnippetStatus for the command.
On success, output includes JSON between __DEXIS_COMP_START__ and __DEXIS_COMP_END__.
JSON includes composite_key, patient, teeth_found, and teeth_missing.

Agent heartbeats and handshake

POST /api/agent/heartbeat (machine endpoint, x-api-key required)
POST /api/agents/handshake (machine endpoint, x-api-key required)

Heartbeat behavior:

Updates lastSeen and tunnel health.
Mirrors tunnel hostname into both publicTunnelUrl and tunnelUrl when present.
Applies OpenClaw auto-recovery after repeated unhealthy checks.
Transitions status to online on recovery.
Marks activity timestamps for idle management accounting.

Handshake behavior:

Publishes tunnel hostname into both publicTunnelUrl and tunnelUrl.
Sets status online.
Updates lastSeen and activity timestamp.

Setup-status behavior:

POST /api/agent/setup-status also mirrors tunnelUrl into both tunnel fields when provided.

OpenClaw-specific endpoints

POST /api/agents/{id}/chat
POST /api/agents/{id}/chat/stream
POST /api/agents/{id}/manage

Autopilot orchestration

POST /api/agents/{id}/autopilot
GET /api/agents/{id}/autopilot

POST actions:

generate-task: convert natural-language intent to task JSON
analyze-script: derive a task plan from existing script + gap prompt
start: start a new orchestration session
cancel: cancel a running session
resume: resume a paused session (optional step override)

GET modes:

?sessionId=<id>: detailed status, current step, attempts, and metrics
no sessionId: list recent sessions for the agent

Autopilot stores step attempts, discovered selectors, and generated stable code. Prefer this for iterative portal hardening while keeping RPA-first execution rules.

Use these for conversational execution and managed tooling flows.

Lifecycle events

Agent lifecycle transitions (idle stop, auto-wake, manual actions) are recorded in the agent_lifecycle_event table and surfaced through two channels:

SSE stream

GET /api/agents/{id}/events now includes lifecycle events alongside existing status, log, and job events:

{
  "type": "lifecycle",
  "eventType": "idle_stop_success",
  "source": "idle_monitor",
  "reason": "Idle for 32 minutes (threshold: 30)",
  "previousStatus": "online",
  "currentStatus": "stopped",
  "timestamp": "2025-01-15T10:30:00Z"
}

Event types: idle_stop_attempt, idle_stop_success, idle_stop_failed, wake_requested, wake_blocked, wake_ready, wake_timeout, wake_failed, manual_start, manual_stop, manual_reboot.

Logs endpoint

GET /api/agents/{id}/logs merges lifecycle events into the unified log timeline alongside provisioning and execution logs.

Lifecycle controls

Agent management endpoints may include deploy, heartbeat, and tunnel operations.

Health probes

GET /api/health lightweight liveness probe with no database dependency (used by AppRunner health checks, bypasses global request timeout middleware)
GET /api/health/deep deep probe with DB connectivity and latency measurement (503 on DB timeout/failure)

Key practices:

Require org ownership on every mutation.
Protect machine endpoints with API keys.
Emit structured lifecycle events for troubleshooting.
All lifecycle actions (start, stop, reboot) are recorded with source, reason, and status transition metadata.

Error handling

Return machine-readable error codes for common categories:

agent_not_found
agent_not_ready
invalid_payload
execution_timeout
permission_denied

Reliability guidance

Treat step-status callbacks as idempotent.
Do not assume ordered callback delivery.
Persist enough context to reconstruct run state after restarts.
Prefer RPA-first selectors and reserve agentic fallback for non-deterministic branches.