Update tasks
In Lattice, a task status represents each stage of the task lifecycle. When an agent receives a task, it calls the following API to update a task in Lattice:
UpdateStatus
: Used to report real-time status updates to Lattice as the agent makes progress through a task.
Before you begin
- To publish taskable entities, and subscribe to tasks, set up your Lattice environment.
- Familiarize yourself with entities and different entity types.
Start performing a task
After an agent has identified a task to perform and begins to make progress towards its objective, it communicates back to Lattice using the UpdateTaskStatus to cycle through various states of a task lifecycle.
To update the status of a task, do the following:
Listen for tasks
Use the ListenAsAgent
operation. In this example, the agent listens for assigned tasks, then updates the task status,
incrementing the StatusVersion
of the task.
Replace AGENT_ID
with the ID of the agent you want to task. If you are developing on Sandboxes,
replace this with the following simulated asset: Demo-Sim-Asset1
:
Assign a task using the UI
To assign a task, do the following:
- Open your environment’s Lattice UI, and choose an asset from the Assets panel. On Sandboxes, choose Demo-Sim-Asset1:
- From the entity pane, choose Task, then
select a task, for example,
Follow
: - From the Task Details panel on the right hand side,
select a target then choose Execute Task:
Task lifecycle
In Lattice tasks move through the following states:
STATUS_MACHINE_RECEIPT
The agent then responds back with status STATUS_MACHINE_RECEIPT
, indicating that the task
has been received, and incrementing statusVersion
accordingly:
STATUS_ACK
When the agent is ready to acknowledge the task, it does so using STATUS_ACK
,
and again increments statusVersion
:
STATUS_EXECUTING
As the agent begins to actively execute the task, it indicates this by reporting STATUS_EXECUTING
back to Lattice:
STATUS_DONE_OK
Finally, when the agent reaches a terminal state and completes the task successfully, it
reports STATUS_DONE_OK
. This might result from operator-initiated requests for task completion:
STATUS_DONE_NOT_OK
If the agent reaches a terminal state but does not complete the task successfully, it
reports STATUS_DONE_NOT_OK
. This might result from operator-initiated requests for task completion or cancellation.
The agent should include a descriptive TaskError
when reporting STATUS_DONE_NOT_OK
:
In this example, the message indicates that the agent encountered an internal error during task execution. You can add more descriptive errors to help the operator troubleshoot the issue accordingly.
The STATUS_DONE_OK
and STATUS_DONE_NOT_OK
statuses are considered terminal states.
Once a task’s reaches either state, it’s complete and cannot be updated.
What’s next
- To learn more about tasks, see Task an asset in in the Lattice SDK sample applications guide.