packages/docs/rest/autonomy.md
The autonomy API controls whether the agent operates autonomously — proactively taking actions, posting, and engaging without user prompts. The autonomy state is managed by the AUTONOMY service in the agent runtime.
The autonomy system is managed by the AUTONOMY service registered in the agent runtime. The service creates a recurring task that the runtime's TaskService picks up and executes on its 1-second polling interval.
The API layer interacts with the autonomy service through this interface:
| Method | Return Type | Description |
|---|---|---|
enableAutonomy() | Promise<void> | Start the autonomous operation loop |
disableAutonomy() | Promise<void> | Stop the loop gracefully |
isLoopRunning() | boolean | Whether the autonomy loop is currently executing a tick |
getStatus() | { enabled?: boolean } | Current enabled state |
The enabled field in the response is resolved from the runtime flag runtime.enableAutonomy === true.
When autonomy is enabled, the triggers system checks runtime.enableAutonomy as a gate before creating trigger-based actions. The autonomy service also exposes:
getAutonomousRoomId() — returns the room UUID used for autonomous conversationsinjectAutonomousInstruction(payload) — injects a one-time instruction into the next autonomy tickGet the current autonomy state.
Response
{
"enabled": true
}
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether autonomous operation is currently enabled |
Enable or disable autonomous operation.
When enabling, the autonomy task fires its first tick immediately. When disabling, the loop is stopped gracefully after the current tick (if any) completes.
Request
{
"enabled": true
}
| Parameter | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes | true to enable autonomy, false to disable |
Response
{
"enabled": true
}
| Field | Type | Description |
|---|---|---|
enabled | boolean | The current autonomy enabled state after the operation |
Behavior Notes
AUTONOMY service is not registered in the runtime, the enabled property is set directly on the runtime objectenabled parameter must be a boolean; non-boolean values return a 400 error| Status | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Request body is malformed or missing required fields |
| 401 | UNAUTHORIZED | Missing or invalid authentication token |
| 404 | NOT_FOUND | Requested resource does not exist |
| 503 | SERVICE_UNAVAILABLE | Autonomy service is not available |
| 500 | AUTONOMY_DISABLED | Autonomy feature is disabled in configuration |
| 500 | INTERNAL_ERROR | Unexpected server error |