feat: TaskKey to propagate name

akka-javasdk-tests/src/test/java/akkajavasdk/agent/task/BacklogEntityTest.java

@@ -11,6 +11,7 @@
 import akka.javasdk.agent.task.BacklogEntity;
 import akka.javasdk.agent.task.BacklogEvent;
 import akka.javasdk.agent.task.BacklogState;
+import akka.javasdk.agent.task.TaskKey;
 import akka.javasdk.testkit.EventSourcedResult;
 import akka.javasdk.testkit.EventSourcedTestKit;
 import org.junit.jupiter.api.Test;
@@ -39,7 +40,8 @@ public void shouldCreateIdempotently() {
   @Test
   public void shouldAddTask() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    EventSourcedResult<Done> result = testKit.method(BacklogEntity::addTask).invoke("task-1");
+    EventSourcedResult<Done> result =
+        testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     assertThat(result.getReply()).isEqualTo(done());
     result.getNextEventOfType(BacklogEvent.TaskAdded.class);
     assertThat(testKit.getState().containsTask("task-1")).isTrue();
@@ -49,21 +51,23 @@ public void shouldAddTask() {
   @Test
   public void shouldAddTaskIdempotently() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
-    EventSourcedResult<Done> result = testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
+    EventSourcedResult<Done> result =
+        testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     assertThat(result.getReply()).isEqualTo(done());
     assertThat(result.getAllEvents()).isEmpty();
   }
 
   @Test
   public void shouldClaimTask() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
 
     EventSourcedResult<Done> result =
         testKit
             .method(BacklogEntity::claim)
             .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));
+
     assertThat(result.getReply()).isEqualTo(done());
     result.getNextEventOfType(BacklogEvent.TaskClaimed.class);
     assertThat(testKit.getState().isClaimed("task-1")).isTrue();
@@ -83,7 +87,7 @@ public void shouldRejectClaimForNonExistentTask() {
   @Test
   public void shouldRejectClaimForAlreadyClaimedTask() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));
@@ -98,7 +102,7 @@ public void shouldRejectClaimForAlreadyClaimedTask() {
   @Test
   public void shouldReleaseClaimedTask() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));
@@ -112,7 +116,7 @@ public void shouldReleaseClaimedTask() {
   @Test
   public void shouldReleaseUnclaimedTaskIdempotently() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
 
     EventSourcedResult<Done> result = testKit.method(BacklogEntity::release).invoke("task-1");
     assertThat(result.getReply()).isEqualTo(done());
@@ -122,7 +126,7 @@ public void shouldReleaseUnclaimedTaskIdempotently() {
   @Test
   public void shouldTransferTask() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));
@@ -140,9 +144,9 @@ public void shouldTransferTask() {
   @Test
   public void shouldCancelUnclaimed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
-    testKit.method(BacklogEntity::addTask).invoke("task-2");
-    testKit.method(BacklogEntity::addTask).invoke("task-3");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-2", "Task Two"));
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-3", "Task Three"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-2", "agent-1"));
@@ -199,14 +203,15 @@ public void shouldRejectAddTaskWhenClosed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
     testKit.method(BacklogEntity::close).invoke();
 
-    EventSourcedResult<Done> result = testKit.method(BacklogEntity::addTask).invoke("task-1");
+    EventSourcedResult<Done> result =
+        testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     assertThat(result.getError()).isEqualTo("Backlog is closed");
   }
 
   @Test
   public void shouldRejectClaimWhenClosed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit.method(BacklogEntity::close).invoke();
 
     EventSourcedResult<Done> result =
@@ -219,7 +224,7 @@ public void shouldRejectClaimWhenClosed() {
   @Test
   public void shouldRejectReleaseWhenClosed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));
@@ -232,7 +237,7 @@ public void shouldRejectReleaseWhenClosed() {
   @Test
   public void shouldRejectTransferWhenClosed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));
@@ -248,7 +253,7 @@ public void shouldRejectTransferWhenClosed() {
   @Test
   public void shouldRejectCancelUnclaimedWhenClosed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit.method(BacklogEntity::close).invoke();
 
     EventSourcedResult<Done> result = testKit.method(BacklogEntity::cancelUnclaimed).invoke();
@@ -258,7 +263,7 @@ public void shouldRejectCancelUnclaimedWhenClosed() {
   @Test
   public void shouldAllowGetStateWhenClosed() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
     testKit.method(BacklogEntity::close).invoke();
 
     EventSourcedResult<BacklogState> result = testKit.method(BacklogEntity::getState).invoke();
@@ -269,8 +274,8 @@ public void shouldAllowGetStateWhenClosed() {
   @Test
   public void shouldGetState() {
     var testKit = EventSourcedTestKit.of(BacklogEntity::new);
-    testKit.method(BacklogEntity::addTask).invoke("task-1");
-    testKit.method(BacklogEntity::addTask).invoke("task-2");
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-1", "Task One"));
+    testKit.method(BacklogEntity::addTask).invoke(new TaskKey("task-2", "Task Two"));
     testKit
         .method(BacklogEntity::claim)
         .invoke(new BacklogEntity.ClaimRequest("task-1", "agent-1"));

akka-javasdk-tests/src/test/java/akkajavasdk/agent/task/TaskClientIntegrationTest.java

@@ -29,7 +29,8 @@ private String newTaskId() {
   public void shouldCreateTask() {
     var taskId = newTaskId();
     var created = componentClient.forTask(taskId).create(TEST_TASK.instructions("do something"));
-    assertThat(created).isEqualTo(taskId);
+    assertThat(created.id()).isEqualTo(taskId);
+    assertThat(created.name()).isEqualTo(TEST_TASK.name());
   }
 
   // --- get ---

akka-javasdk-tests/src/test/java/akkajavasdk/components/agent/autonomous/AgentLifecycleIntegrationTest.java

@@ -79,11 +79,11 @@ public void shouldPauseAndResumeAgent() {
     var state = agentClient.getState();
     assertThat(state.paused()).isTrue();
 
-    var taskId =
+    var taskKey =
         componentClient
             .forTask(UUID.randomUUID().toString())
             .create(TestTasks.TEST_TASK.instructions("Do something."));
-    agentClient.assignTasks(taskId);
+    agentClient.assignTasks(taskKey);
 
     agentClient.resume();
 
@@ -92,7 +92,7 @@ public void shouldPauseAndResumeAgent() {
         .atMost(10, TimeUnit.SECONDS)
         .untilAsserted(
             () -> {
-              var snapshot = componentClient.forTask(taskId).get(TestTasks.TEST_TASK);
+              var snapshot = componentClient.forTask(taskKey.id()).get(TestTasks.TEST_TASK);
               assertThat(snapshot.result()).isNotNull();
             });
 

akka-javasdk/src/main/java/akka/javasdk/agent/task/BacklogEntity.java

@@ -40,15 +40,17 @@ public Effect<Done> create(String name) {
     return effects().persist(new BacklogEvent.BacklogCreated(name)).thenReply(__ -> done());
   }
 
-  /** Add a task ID reference to this backlog. The task must already exist in TaskEntity. */
-  public Effect<Done> addTask(String taskId) {
+  /** Add a task reference to this backlog. The task must already exist in TaskEntity. */
+  public Effect<Done> addTask(TaskKey taskKey) {
     if (currentState().closed()) {
       return closedError();
     }
-    if (currentState().containsTask(taskId)) {
+    if (currentState().containsTask(taskKey.id())) {
       return effects().reply(done()); // idempotent
     }
-    return effects().persist(new BacklogEvent.TaskAdded(taskId)).thenReply(__ -> done());
+    return effects()
+        .persist(new BacklogEvent.TaskAdded(taskKey.id(), taskKey.name()))
+        .thenReply(__ -> done());
   }
 
   /** Atomic first-come-first-served claim. */
@@ -128,7 +130,7 @@ private Effect<Done> closedError() {
   public BacklogState applyEvent(BacklogEvent event) {
     return switch (event) {
       case BacklogEvent.BacklogCreated e -> currentState().withName(e.name());
-      case BacklogEvent.TaskAdded e -> currentState().withTaskAdded(e.taskId());
+      case BacklogEvent.TaskAdded e -> currentState().withTaskAdded(e.taskId(), e.taskName());
       case BacklogEvent.TaskClaimed e -> currentState().withTaskClaimed(e.taskId(), e.claimedBy());
       case BacklogEvent.TaskReleased e -> currentState().withTaskReleased(e.taskId());
       case BacklogEvent.TaskTransferred e ->

akka-javasdk/src/main/java/akka/javasdk/agent/task/BacklogEvent.java

@@ -12,7 +12,7 @@ public sealed interface BacklogEvent {
   record BacklogCreated(String name) implements BacklogEvent {}
 
   @TypeName("akka-backlog-task-added")
-  record TaskAdded(String taskId) implements BacklogEvent {}
+  record TaskAdded(String taskId, String taskName) implements BacklogEvent {}
 
   @TypeName("akka-backlog-task-claimed")
   record TaskClaimed(String taskId, String claimedBy) implements BacklogEvent {}

akka-javasdk/src/main/java/akka/javasdk/agent/task/BacklogState.java

@@ -9,10 +9,10 @@
 import java.util.Optional;
 
 /** State of a backlog entity — tracks task references and their claim status. */
-public record BacklogState(String name, Map<String, Optional<String>> tasks, boolean closed) {
+public record BacklogState(String name, Map<String, Entry> tasks, boolean closed) {
 
-  /** An entry in the backlog: task ID and who has claimed it (if anyone). */
-  public record Entry(String taskId, Optional<String> claimedBy) {}
+  /** An entry in the backlog: task ID, task name, and who has claimed it (if anyone). */
+  public record Entry(String taskId, String taskName, Optional<String> claimedBy) {}
 
   public static BacklogState empty() {
     return new BacklogState("", Map.of(), false);
@@ -31,27 +31,33 @@ public boolean containsTask(String taskId) {
   }
 
   public boolean isClaimed(String taskId) {
-    return tasks.containsKey(taskId) && tasks.get(taskId).isPresent();
+    return tasks.containsKey(taskId) && tasks.get(taskId).claimedBy().isPresent();
+  }
+
+  public String taskName(String taskId) {
+    var entry = tasks.get(taskId);
+    return entry != null ? entry.taskName() : "";
   }
 
   public Optional<String> claimedBy(String taskId) {
-    return tasks.getOrDefault(taskId, Optional.empty());
+    var entry = tasks.get(taskId);
+    return entry != null ? entry.claimedBy() : Optional.empty();
   }
 
   public List<Entry> entries() {
-    return tasks.entrySet().stream().map(e -> new Entry(e.getKey(), e.getValue())).toList();
+    return List.copyOf(tasks.values());
   }
 
   public List<String> unclaimedTaskIds() {
     return tasks.entrySet().stream()
-        .filter(e -> e.getValue().isEmpty())
+        .filter(e -> e.getValue().claimedBy().isEmpty())
         .map(Map.Entry::getKey)
         .toList();
   }
 
   public List<String> claimedTaskIds() {
     return tasks.entrySet().stream()
-        .filter(e -> e.getValue().isPresent())
+        .filter(e -> e.getValue().claimedBy().isPresent())
         .map(Map.Entry::getKey)
         .toList();
   }
@@ -60,27 +66,31 @@ public BacklogState withName(String name) {
     return new BacklogState(name, tasks, closed);
   }
 
-  public BacklogState withTaskAdded(String taskId) {
+  public BacklogState withTaskAdded(String taskId, String taskName) {
     var updated = new java.util.HashMap<>(tasks);
-    updated.put(taskId, Optional.empty());
+    updated.put(taskId, new Entry(taskId, taskName, Optional.empty()));
     return new BacklogState(name, Map.copyOf(updated), closed);
   }
 
   public BacklogState withTaskClaimed(String taskId, String claimedBy) {
     var updated = new java.util.HashMap<>(tasks);
-    updated.put(taskId, Optional.of(claimedBy));
+    var existing = updated.get(taskId);
+    var taskName = existing != null ? existing.taskName() : "";
+    updated.put(taskId, new Entry(taskId, taskName, Optional.of(claimedBy)));
     return new BacklogState(name, Map.copyOf(updated), closed);
   }
 
   public BacklogState withTaskReleased(String taskId) {
     var updated = new java.util.HashMap<>(tasks);
-    updated.put(taskId, Optional.empty());
+    var existing = updated.get(taskId);
+    var taskName = existing != null ? existing.taskName() : "";
+    updated.put(taskId, new Entry(taskId, taskName, Optional.empty()));
     return new BacklogState(name, Map.copyOf(updated), closed);
   }
 
   public BacklogState withUnclaimedRemoved() {
     var updated = new java.util.HashMap<>(tasks);
-    updated.entrySet().removeIf(e -> e.getValue().isEmpty());
+    updated.entrySet().removeIf(e -> e.getValue().claimedBy().isEmpty());
     return new BacklogState(name, Map.copyOf(updated), closed);
   }
 

akka-javasdk/src/main/java/akka/javasdk/agent/task/TaskKey.java

@@ -0,0 +1,13 @@
+/*
+ * Copyright (C) 2021-2026 Lightbend Inc. <https://www.lightbend.com>
+ */
+
+package akka.javasdk.agent.task;
+
+/** A reference to a task, holding its ID and name. */
+public record TaskKey(String id, String name) {
+  @Override
+  public String toString() {
+    return name + "|" + id;
+  }
+}

akka-javasdk/src/main/java/akka/javasdk/client/AutonomousAgentClient.java

@@ -12,6 +12,7 @@
 import akka.javasdk.agent.autonomous.AutonomousAgent;
 import akka.javasdk.agent.autonomous.Notification;
 import akka.javasdk.agent.task.Task;
+import akka.javasdk.agent.task.TaskKey;
 import akka.stream.javadsl.Source;
 import java.util.concurrent.CompletionStage;
 
@@ -47,18 +48,18 @@ default String runSingleTask(Task<?> task) {
    * Assign one or more previously created tasks to this agent. Tasks are queued if the agent is
    * busy.
    *
-   * @param taskIds IDs of previously created tasks
+   * @param taskKeys references to previously created tasks
    */
-  default void assignTasks(String... taskIds) {
-    assignTasksAsync(taskIds).toCompletableFuture().join();
+  default void assignTasks(TaskKey... taskKeys) {
+    assignTasksAsync(taskKeys).toCompletableFuture().join();
   }
 
   /**
    * Async variant of {@link #assignTasks}.
    *
-   * @param taskIds IDs of previously created tasks
+   * @param taskKeys references to previously created tasks
    */
-  CompletionStage<Done> assignTasksAsync(String... taskIds);
+  CompletionStage<Done> assignTasksAsync(TaskKey... taskKeys);
 
   /**
    * Apply per-instance configuration to this agent. The goal overrides the static goal from the