Add metadata() method to TaskBaseBuilder for task metadata configuration

[ricardozanini]

Feature Request

Summary

Add a metadata() method to TaskBaseBuilder to allow fluent configuration of task metadata, particularly for UI visualization purposes.

Current State

• TaskBase already has a metadata field of type TaskMetadata
• TaskMetadata is a map-based additional properties holder
• Missing: No fluent builder method in TaskBaseBuilder to set this metadata

Use Case

In Quarkus Flow (quarkiverse/quarkus-flow), we're building LangChain4j agentic workflows that generate workflow tasks at build-time and runtime. These workflows render topology visualizations in Quarkus dev-ui.

For loop and conditional workflows, we have metadata like:

• exitConditionDescription for loop tasks - describes when the loop exits
• conditionDescription for conditional tasks - describes routing logic

Currently, we store this in flow objects, but it would be more natural to attach it directly to the task metadata for UI consumption.

Proposed API

Following the pattern from DocumentBuilder.metadata():

public abstract class TaskBaseBuilder<T extends TaskBaseBuilder<T>> {
    // ... existing code ...
    
    public T metadata(Consumer<TaskMetadataBuilder> metadataConsumer) {
        final TaskMetadataBuilder metadataBuilder = new TaskMetadataBuilder();
        metadataConsumer.accept(metadataBuilder);
        this.task.setMetadata(metadataBuilder.build());
        return self();
    }
}

With a builder:

public class TaskMetadataBuilder {
    private TaskMetadata metadata = new TaskMetadata();
    
    public TaskMetadataBuilder put(String key, Object value) {
        metadata.setAdditionalProperty(key, value);
        return this;
    }
    
    // Convenience method for common "description" metadata
    public TaskMetadataBuilder description(String description) {
        return put("description", description);
    }
    
    public TaskMetadata build() {
        return metadata;
    }
}

Example Usage

tasks.function("loop-task-0", fn -> fn
    .function((scope, ctx) -> executeAgent(scope, 0))
    .metadata(meta -> meta.description("Exit when counter reaches 10"))
);

Benefits

1. UI Visualization: Dev tools and UIs can display task descriptions from metadata
2. Consistency: Aligns with existing DocumentBuilder.metadata() pattern
3. Extensibility: Additional properties map allows custom metadata without schema changes
4. Separation of Concerns: Task execution logic stays separate from UI/descriptive metadata

Related

• Open Workflow Spec: Tasks already have metadata field defined
• Pattern precedent: DocumentBuilder has similar metadata() method

Would you like me to submit a PR for this enhancement?