Controller API

The Controller API exposes a single endpoint for managing the lifecycle of an active inference task. Use it to pause a running agent, resume a stopped one, or restart a task from scratch with a new task ID.

All endpoints require authentication. See Configuration Reference for auth options.

---

PUT /controller/state/{task_id}/{state_id}

Update the state of an active inference controller.

Path parameters

Parameter	Type	Description
task_id	string	The task ID returned by POST /event/infer
state_id	"run" | "stop" | "restart"	The target state

State transitions

state_id	Effect
run	Resume a stopped controller. Dispatches any pending events.
stop	Pause the controller. No new events are dispatched until run is called.
restart	Abort the current task and start a new one with a fresh task ID. The original inference command is replayed from the beginning.

Response — 200 OK

Returns the updated CommonAttributes object for the task:

{
  "task_id": "task-newid456",
  "assistant_id": "support-agent",
  "agentspace_id": "default",
  "user_id": "user-1",
  "session_id": "session-abc"
}

On restart, task_id in the response is the new task ID. Use it to open a new SSE stream.

Error responses

Status	Condition
401	Missing or invalid Authorization header
404	No active controller found for task_id

Examples

# Stop a running task
curl -X PUT "http://localhost:8080/controller/state/task-abc123/stop" \
  -H "Authorization: Bearer $API_TOKEN"

# Resume a stopped task
curl -X PUT "http://localhost:8080/controller/state/task-abc123/run" \
  -H "Authorization: Bearer $API_TOKEN"

# Restart a task (returns a new task_id)
RESPONSE=$(curl -s -X PUT "http://localhost:8080/controller/state/task-abc123/restart" \
  -H "Authorization: Bearer $API_TOKEN")

NEW_TASK_ID=$(echo $RESPONSE | jq -r '.task_id')

# Stream the restarted task
curl -N "http://localhost:8080/event/stream/$NEW_TASK_ID" \
  -H "Authorization: Bearer $API_TOKEN"

---

How the controller works

The AssistantInferenceController is a state machine stored in Redis under the controller-{task_id} key. It receives CloudEvents from the Kafka worker dispatcher, advances the execution state, and emits new events for the next step.

The controller is created automatically when the first assistant.inference.v1 event arrives for a task. It persists in Redis until the task completes or the TTL expires (REDIS_TTL, default 24 hours).

Controller states

State	Description
running	Default. Processing events and dispatching new ones.
stopped	Paused. Incoming events are accepted but no new events are dispatched.

The restart operation is not a state — it creates a new controller with a new task ID and replays the original inference command.

---

Related pages

• Inference Endpoints — POST /event/infer and GET /event/stream
• Kafka & Event Bus — the Kafka event pipeline that drives the controller
• Configuration Reference — CONTROLLER_TOPIC_PREFIX and REDIS_TTL