Agents API

Agent endpoints cover lifecycle control, execution, 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}/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

OpenClaw-specific endpoints

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

Use these for conversational execution and managed tooling flows.

Lifecycle controls

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

Key practices:

• Require org ownership on every mutation.
• Protect machine endpoints with API keys.
• Emit structured telemetry for troubleshooting.

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.