Integrate with Lattice Tasking

This page describes how to integrate with Task Manager, the service that lets you create, update, monitor, and execute a task.

Task Management

Task Manager handles task state management and the correct routing of tasks to taskable agents.

In an integration with Lattice, operators and taskable agents interact with Task Manager to progress a task through its full lifecycle of creation to completion.

Endpoints for taskable agents

If you're integrating an agent with Lattice's tasking infrastructure, your robot should only use the following endpoints:

• ListenAsAgent: monitor for and receive tasks.
• UpdateStatus: report real-time status updates to Task Manager as the agent progresses through a task.

Define your agent's tasks

To ensure Lattice knows your agent can complete specific tasks, add TaskDefinitions in the entity's TaskCatalog field. The TaskCatalog specifies the types of tasks an agent can perform.

Lattice will not send a task to an agent for execution unless the task is listed in the agent's TaskCatalog.

Here's an example of an entity's TaskCatalog:

"taskCatalog": {
  "taskDefinitions": [
    {
      "taskSpecificationUrl": "type.googleapis.com/anduril.tasks.v2.VisualId"
    },
    {
      "taskSpecificationUrl": "type.googleapis.com/anduril.tasks.v2.Investigate”
    }
  ]
}

In the example above, the agent can execute:

• A "Visual Id" task, which might involve identifying or tracking visual targets.
• An "Investigate" task, which might involve reconnaissance or surveillance.

Each task definition requires a taskSpecificationUrl, which is a URL that uniquely identifies the task's protobuf message type.

info

You will need to work with your Anduril representative to determine an appropriate task specification.

Publish your TaskCatalog

Once you've defined the tasks your agent can complete, publish your entity via the PublishEntity API.

Subscribe to tasks

With the ListenAsAgent endpoint, your asset can subscribe to tasks that Task Manager routes to it and monitor for task updates. If a task is assigned to an agent that is not monitoring this endpoint, the task will fail to send.

For example, the following snippet imports the Task Manager API and streams tasks for the entityIds listed in the request, to be executed by the agent:

import (
    "context"
    "fmt"
    "github.com/anduril/lattice-sdk-go/src/anduril/taskmanager/v1"
)

func listenAsAgent(client taskmanager.TaskManagerAPIClient, entityIDs []string) error {
    ctx := context.Background()
    req := &taskmanager.ListenAsAgentRequest{
        AgentSelector: &taskmanager.ListenAsAgentRequest_EntityIds{
            EntityIds: &taskmanager.EntityIds{
                EntityIds: entityIDs,
            },
        },
    }
    stream, err := client.ListenAsAgent(ctx, req)
    if err != nil {
        return fmt.Errorf("error setting up ListenAsAgent: %v", err)
    }
    for {
        resp, err := stream.Recv()
        if err != nil {
            return fmt.Errorf("error receiving from ListenAsAgent stream: %v", err)
        }
        processExecuteRequest(resp.GetExecuteRequest())
    }
}

Handle stream interruptions

Agents should gracefully handle stream interruptions. If the connection to Task Manager fails, the stream will close. Your system should handle potential stream errors and retry the connection to Task Manager when necessary. This ensures the agent maintains its subscription to task updates, even during transient network or service interruptions.

Update task status

The agent uses the UpdateStatus endpoint to move a task along its task lifecycle and report any errors.

For example, the following snippet imports the Task Manager API and updates a task with a new task status:

import (
    "context"
    "fmt"
    "github.com/anduril/lattice-sdk-go/src/anduril/taskmanager/v1"
)

func updateTaskStatus(client taskmanager.TaskManagerAPIClient, taskID string, newStatus taskmanager.Status) error {
    ctx := context.Background()
    statusUpdate := &taskmanager.StatusUpdate{
        Version: &taskmanager.TaskVersion{
            TaskId: taskID,
            // You will need to provide the specific version of the task you are updating here.
            // StatusVersion: <current_status_version>,
            // DefinitionVersion: <current_definition_version>
        },
        Status: &taskmanager.TaskStatus{
            Status: newStatus, // For example, newStatus could be taskmanager.Status_STATUS_EXECUTING
        },
                // The author of the status update, which is the entity reporting status updates
        Author: &taskmanager.Principal{
            Agent: &taskmanager.Principal_System{
                System: &taskmanager.System{
                    EntityId: "test-entity"
                },
            },
        },
    }
    req := &taskmanager.UpdateStatusRequest{
        StatusUpdate: statusUpdate,
    }
    _, err := client.UpdateStatus(ctx, req)
    if err != nil {
        return fmt.Errorf("error updating task status: %v", err)
    }
    return nil
}

Endpoints for operators

The operator should use the following endpoints from Lattice UI or a third-party UI:

• CreateTask: creates a new task. Lattice calls the CreateTask endpoint after a task's details have been populated in the UI, and an operator presses "Execute Task" for the first time.
• GetTask: gets the state of an existing task.
• QueryTasks: find tasks that match request criteria.