Package io.a2a.server.tasks

Interface TaskStore

All Known Implementing Classes:

InMemoryTaskStore

public interface TaskStore

Storage interface for managing task persistence across the task lifecycle.

TaskStore is responsible for persisting task state including status updates, artifacts, message history, and metadata. It's called by DefaultRequestHandler and TaskManager to save task state as agents process requests and generate events.

Persistence Guarantees

Tasks are persisted:

• After each status update event (SUBMITTED, WORKING, COMPLETED, etc.)
• After each artifact is added
• Before events are distributed to clients (ensures consistency)
• Before push notifications are sent

Persistence happens synchronously before responses are returned, ensuring clients always see committed state.

Default Implementation

InMemoryTaskStore:

• Stores tasks in ConcurrentHashMap
• Also implements TaskStateProvider for queue lifecycle decisions
• Thread-safe for concurrent operations
• Tasks lost on application restart

Alternative Implementations

• extras/task-store-database-jpa: JpaDatabaseTaskStore with PostgreSQL/MySQL persistence

Database implementations:

• Survive application restarts
• Enable task sharing across server instances
• Typically also implement TaskStateProvider for integrated state queries
• Support transaction boundaries for consistency

Relationship to TaskStateProvider

Many TaskStore implementations also implement TaskStateProvider to provide queue lifecycle management with task state information:

 @ApplicationScoped
 public class InMemoryTaskStore implements TaskStore, TaskStateProvider {
     // Provides both persistence and state queries
     public boolean isTaskFinalized(String taskId) {
         Task task = tasks.get(taskId);
         return task != null && task.status().state().isFinal();
     }
 }
 

CDI Extension Pattern

 @ApplicationScoped
 @Alternative
 @Priority(50)  // Higher than default InMemoryTaskStore
 public class JpaDatabaseTaskStore implements TaskStore, TaskStateProvider {
     @PersistenceContext
     EntityManager em;

     @Transactional
     public void save(Task task) {
         TaskEntity entity = toEntity(task);
         em.merge(entity);
     }
 }
 

Thread Safety

Implementations must be thread-safe. Multiple threads will call methods concurrently for different tasks. Concurrent save() calls for the same task must handle conflicts appropriately (last-write-wins, optimistic locking, etc.).

List Operation Performance

The list(io.a2a.spec.ListTasksParams) method may need to scan and filter many tasks. Database implementations should:

• Use indexes on contextId, status, lastUpdatedAt
• Implement efficient pagination with stable ordering
• Consider caching for frequently-accessed task lists

See Also:

• TaskManager
• TaskStateProvider
• InMemoryTaskStore
• DefaultRequestHandler

Method Summary

Modifier and Type	Method	Description
void	delete(String taskId)	Deletes a task by its ID.
@Nullable Task	get(String taskId)	Retrieves a task by its ID.
ListTasksResult	list(ListTasksParams params)	List tasks with optional filtering and pagination.
void	save(Task task, boolean isReplicated)	Saves or updates a task.

Method Details

save

void save(Task task,
 boolean isReplicated)

Saves or updates a task.

Parameters:

task - the task to save

isReplicated - true if this task update came from a replicated event, false if it originated locally. Used to prevent feedback loops in replicated scenarios (e.g., don't fire TaskFinalizedEvent for replicated updates)

get

@Nullable Task get(String taskId)

Retrieves a task by its ID.

Parameters:

taskId - the task identifier

Returns:

the task if found, null otherwise

delete

void delete(String taskId)

Deletes a task by its ID.

Parameters:

taskId - the task identifier

list

ListTasksResult list(ListTasksParams params)

List tasks with optional filtering and pagination.

Parameters:

params - the filtering and pagination parameters

Returns:

the list of tasks matching the criteria with pagination info