Command agents and operate on tasks
Operators use the Tasks API to create, monitor, and manage tasks across their operational domain.
The specific tasks you command, and monitor, in Lattice depend on the mission requirements, and the environment you’re integrating with. This page shows you how to use the Lattice Sandboxes to create, monitor, and cancel tasks.
The CreateTask (REST)
API lets you create tasks in Lattice using custom task definitions published to the Lattice Schema Registry.
The StreamTasks (REST | gRPC)
API provides centralized visibility into task creation, updates, and status changes for all tasks in your environment.
The CancelTask (REST | gRPC)
API allows you to request cancellation of tasks that are no longer needed.
Before you begin
- To create, monitor, or cancel tasks, set up your Lattice environment.
- Familiarize yourself with tasks and the task lifecycle.
- To create custom tasks, publish your schemas to the Lattice Schema Registry (LSR).
Create tasks using REST
When working with custom tasks using REST:
- First, you retrieve your JSON Schema definitions from the Schema Registry.
- Then you validate your task data against these schema definitions.
- Finally, you use the validated data to create tasks in Lattice using the
CreateTaskAPI.
The Lattice Schema Registry (LSR) lets you validate your task data using JSON schema:
Log in to the LSR using your credentials.
To create a task using a custom task definition, do the following:
Prepare your task data
Define the data for your custom task that matches your schema structure.
This data will be encapsulated in the specification
field of the CreateTaskRequest message.
Validate task data using the schema
Before sending data to Lattice, validate it against the JSON Schema to ensure it matches your custom task definition. This prevents issues when submitting invalid task data to the API.
Create the task using validated data
Use the CreateTask API to submit your task to Lattice. This API expects the following key fields:
description: A human-readable description of the task (up to 4096 characters).specification: Your validated task data wrapped in a Google Protocol BufferAnymessage.author: Information about who or what created the task.relations: Relationships for the task, such as a parent task or an assignee. Setrelations.assigneeto the agent’sPrincipalto route the task to that agent for execution.
The response contains a Task object with details including the assigned task ID and initial status,
which starts as STATUS_CREATED in the task lifecycle.
Create tasks using gRPC
When you use gRPC, the Protobuf types are generated from your task definition directly, so there’s
no separate JSON schema validation step. Instead, the compiler enforces the task’s shape. You build your
custom task message, pack it into the specification
Any field, and call CreateTask.
Build and pack the task specification
Construct your Objective message from the bindings generated from your
task definition, then pack it into a google.protobuf.Any. The
type URL on the Any is what lets the receiving agent identify and unpack the task:
Create the task
Call the CreateTask
RPC with the packed specification. Set the following key fields on the
CreateTaskRequest:
specification: Your custom task message packed into agoogle.protobuf.Any.author: ThePrincipal— a user or system — creating the task.relations.assignee: The agent’sPrincipal. Set this to route the task to that agent for execution.description: A human-readable description of the task.
The response contains the created Task,
including its assigned task ID.
Monitor tasks
The StreamTasks (REST | gRPC)
API establishes a server-sent events (SSE) stream that lets you monitor tasks in Lattice:
Initialize the task stream
In the following example, we specify a prefix to filter the task stream with:
The StreamTasks method accepts the following parameters:
The interval in milliseconds at which the server sends heartbeat events (default: 30000 ms). Use heartbeats to verify the connection is still active. The minimum is 1000 ms; smaller values are raised to 1000 ms.
When set to true, the stream will only include tasks created after the stream starts.
When false (default), existing tasks will also be included in the stream.
Specifies which task types to include in the stream. Can filter by exact match or by prefix.
Only include tasks whose type starts with the specified prefix.
For example, type.googleapis.com/<your-organization.tasks>.
Only include tasks specified in the list. You must list the full URL of the task definition for each of the tasks you want to filter from the stream.
Cancel tasks
The CancelTask API cancels a task by marking it for cancellation in the system.
The behavior depends on the task’s current state:
- If the task has not been sent to an agent, it cancels immediately and transitions to a terminal state
(
STATUS_DONE_NOT_OKwithERROR_CODE_CANCELLED). - If the task has been sent to an agent, the cancellation request is routed to the agent, which decides whether to accept or reject the cancellation.
This section covers the operator’s side of cancellation: sending the request and reading the result. The agent that receives the routed request must set up a task processor and handle cancellation requests — see Handle task cancellation in the agent integration guide.
Request task cancellation
Send a task cancellation request to Lattice. If the task has already been sent to an agent, Lattice routes the request to the agent:
The CancelTask API accepts the following parameters:
The unique identifier of the task to cancel.
Run the cancellation request with the ID of the task you want to cancel:
Verify the results
After requesting cancellation, the task will transition to one of two outcomes:
Successful cancellation:
When the agent accepts the cancellation, the task transitions to
STATUS_DONE_NOT_OK with ERROR_CODE_CANCELLED:
Rejected cancellation:
When the agent rejects the cancellation, the task retains its current status but includes a
TaskError with ERROR_CODE_REJECTED:
For more information, see CancelTask in the Lattice API Reference.
What’s next
- Learn how to integrate an agent to listen for, and process, tasks using the Lattice SDK.