Package akka.javasdk.client

Interface TaskClient

@DoNotInherit public interface TaskClient
Client for creating, querying, and completing tasks, bound to a specific task entity ID.

Not for user extension or instantiation, returned by the SDK component client.

  • Method Details

    • create

      default <R> String create(Task<R> task)
      Create a task entity. The task definition provides the type, description, and instructions. Returns the task ID (the same ID this client was created with).
      Type Parameters:
      R - the result type of the task
      Parameters:
      task - the task to create, with instructions and any attachments
      Returns:
      the task ID

    • createAsync

      <R> CompletionStage<String> createAsync(Task<R> task)
      Async variant of create(akka.javasdk.agent.task.Task<R>).
      Type Parameters:
      R - the result type of the task
      Parameters:
      task - the task to create, with instructions and any attachments
      Returns:
      a CompletionStage with the task ID

    • assign

      default void assign(String assignee)
      Assign a task to an owner. A task must be assigned before it can be completed or failed. For agent-processed tasks, assignment is handled by the runtime. For tasks completed by humans or other processes, the application assigns the task via this method.
      Parameters:
      assignee - identifier of the owner (e.g., a user ID, team name, or process identifier)

    • assignAsync

      CompletionStage<akka.Done> assignAsync(String assignee)
      Async variant of assign(java.lang.String).
      Parameters:
      assignee - identifier of the owner (e.g., a user ID, team name, or process identifier)
      Returns:
      a CompletionStage that completes when the task has been assigned

    • complete

      default <R> void complete(TaskDefinition<R> taskDefinition, R result)
      Complete a task with a typed result. The task must be assigned first (via assign(java.lang.String) or by the agent runtime). For tasks not yet in progress, completion is allowed directly from the assigned state — no separate start step is needed.
      Type Parameters:
      R - the result type of the task
      Parameters:
      taskDefinition - the task definition, used for result type validation
      result - the task result

    • completeAsync

      <R> CompletionStage<akka.Done> completeAsync(TaskDefinition<R> taskDefinition, R result)
      Async variant of complete(akka.javasdk.agent.task.TaskDefinition<R>, R).
      Type Parameters:
      R - the result type of the task
      Parameters:
      taskDefinition - the task definition, used for result type validation
      result - the task result
      Returns:
      a CompletionStage that completes when the task has been completed

    • fail

      default void fail(String reason)
      Fail a task with a reason. The task must be assigned first (via assign(java.lang.String) or by the agent runtime).
      Parameters:
      reason - the failure reason

    • failAsync

      CompletionStage<akka.Done> failAsync(String reason)
      Async variant of fail(java.lang.String).
      Parameters:
      reason - the failure reason
      Returns:
      a CompletionStage that completes when the task has been failed

    • get

      default <R> TaskSnapshot<R> get(TaskDefinition<R> taskDefinition)
      Get a point-in-time snapshot of the task's current state.

      The supplied TaskDefinition is validated against the task entity: if its name or result type does not match the definition the task was created with, TaskException.TypeMismatch is thrown. This guards against accidentally reading a task with the wrong definition (for example, calling forTask(taskId).get(OtherTasks.SOMETHING_ELSE) on an id that was created with a different task) and ensures the returned result can be safely deserialized as R.

      Type Parameters:
      R - the result type of the task
      Parameters:
      taskDefinition - the task definition, used for typed result deserialization
      Returns:
      the task snapshot containing status and typed result
      Throws:
      TaskException.TypeMismatch - if the task's name or result type does not match taskDefinition

    • getAsync

      <R> CompletionStage<TaskSnapshot<R>> getAsync(TaskDefinition<R> taskDefinition)
      Async variant of get(akka.javasdk.agent.task.TaskDefinition<R>).

      The returned CompletionStage fails with TaskException.TypeMismatch if the task's name or result type does not match taskDefinition.

      Type Parameters:
      R - the result type of the task
      Parameters:
      taskDefinition - the task definition, used for typed result deserialization
      Returns:
      a CompletionStage with the task snapshot containing status and typed result

    • result

      default <R> R result(TaskDefinition<R> taskDefinition)
      Blocks until the task reaches a terminal state and returns the typed result.

      As with get(akka.javasdk.agent.task.TaskDefinition<R>), the supplied TaskDefinition is validated against the task entity.

      Type Parameters:
      R - the result type of the task
      Parameters:
      taskDefinition - the task definition, used for typed result deserialization
      Returns:
      the typed task result
      Throws:
      TaskException.Failed - if the task failed
      TaskException.Cancelled - if the task was cancelled
      TaskException.TypeMismatch - if the task's name or result type does not match taskDefinition

    • resultAsync

      <R> CompletionStage<R> resultAsync(TaskDefinition<R> taskDefinition)
      Async variant of result(akka.javasdk.agent.task.TaskDefinition<R>).

      The returned CompletionStage fails with TaskException.Failed if the task failed, TaskException.Cancelled if it was cancelled, or TaskException.TypeMismatch if the task's name or result type does not match taskDefinition.

      Type Parameters:
      R - the result type of the task
      Parameters:
      taskDefinition - the task definition, used for typed result deserialization
      Returns:
      a CompletionStage with the typed task result

    • notificationStream

      akka.stream.javadsl.Source<TaskNotification,akka.NotUsed> notificationStream()
      Subscribe to notifications published by the task entity. See TaskNotification for the event catalog.
      Returns:
      a source of task notification events