PlanTask

💡 This middleware was introduced in v0.8.0. Package path: github.com/cloudwego/eino/adk/middlewares/plantask

Overview

plantask is a task management middleware that injects four tools into the Agent via the BeforeAgent hook, providing structured task planning capabilities:

TaskCreate

TaskGet

TaskUpdate

TaskList

Core use case: Break down complex requests into trackable sub-tasks, manage dependencies between tasks, and show execution progress to the user.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              Agent                                      │
│                                                                         │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │  BeforeAgent: Inject task tools (with sync.Mutex for concurrency) │  │
│  │    - TaskCreate                                                    │  │
│  │    - TaskGet                                                       │  │
│  │    - TaskUpdate                                                    │  │
│  │    - TaskList                                                      │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                             Backend                                     │
│                                                                         │
│  Storage structure:                                                     │
│    baseDir/                                                             │
│    ├── .highwatermark    # Maximum allocated ID (plain-text number)     │
│    ├── 1.json            # Task #1                                      │
│    ├── 2.json            # Task #2                                      │
│    └── ...                                                              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

API

Constructor

// Generic version, supports *schema.Message and *schema.AgenticMessage
func NewTyped[M adk.MessageType](ctx context.Context, config *Config) (adk.TypedChatModelAgentMiddleware[M], error)

// Non-generic version, equivalent to NewTyped[*schema.Message]
func New(ctx context.Context, config *Config) (adk.ChatModelAgentMiddleware, error)

Config

type Config struct {
    Backend Backend  // Storage backend, required
    BaseDir string   // Task file storage directory, required
}

💡 The Backend should be isolated at the session level — different sessions should correspond to different Backend instances (i.e., different task lists).

Backend Interface

Backend is defined within the plantask package and is a minimal subset of filesystem.Backend, retaining only the four methods needed for task storage:

type Backend interface {
    LsInfo(ctx context.Context, req *LsInfoRequest) ([]FileInfo, error)
    Read(ctx context.Context, req *ReadRequest) (*filesystem.FileContent, error)
    Write(ctx context.Context, req *WriteRequest) error
    Delete(ctx context.Context, req *DeleteRequest) error
}

Type alias relationships:

type FileInfo = filesystem.FileInfo        // Path, IsDir, Size, ModifiedAt
type LsInfoRequest = filesystem.LsInfoRequest  // Path string
type ReadRequest = filesystem.ReadRequest       // FilePath, Offset, Limit
type WriteRequest = filesystem.WriteRequest     // FilePath, Content string

// DeleteRequest is custom to the plantask package (not present in the filesystem package)
type DeleteRequest struct {
    FilePath string
}

💡 Note that Read returns *filesystem.FileContent (containing a Content string field), not a raw string. Import path: github.com/cloudwego/eino/adk/filesystem.

Task Structure

type task struct {
    ID          string         `json:"id"`
    Subject     string         `json:"subject"`
    Description string         `json:"description"`
    Status      string         `json:"status"`
    Blocks      []string       `json:"blocks"`
    BlockedBy   []string       `json:"blockedBy"`
    ActiveForm  string         `json:"activeForm,omitempty"`
    Owner       string         `json:"owner,omitempty"`
    Metadata    map[string]any `json:"metadata,omitempty"`
}

Status

pending

in_progress

completed

deleted

Status transitions: pending → in_progress → completed; any status can be directly set to deleted.

Tool Parameters

TaskCreate

Tool name constant: TaskCreateToolName = "TaskCreate"

subject

description

activeForm

metadata

After creation, the task ID auto-increments (based on the .highwatermark file) and the initial status is pending.

TaskGet

Tool name constant: TaskGetToolName = "TaskGet"

taskId

Returns the complete task information: subject, description, status, blocks, blockedBy, owner.

TaskUpdate

Tool name constant: TaskUpdateToolName = "TaskUpdate"

taskId

subject

description

activeForm

status

pending

in_progress

completed

deleted

addBlocks

addBlockedBy

owner

metadata

Key behaviors:

• status: "deleted" physically deletes the task file and removes the ID from all other tasks’ blocks/blockedBy lists
• Circular dependency detection is performed when adding dependencies; an error is raised if a cycle is formed
• When all tasks are completed, all task files are automatically deleted (cleanup mechanism)

TaskList

Tool name constant: TaskListToolName = "TaskList"

No parameters. Returns a summary list of all tasks (sorted by ID), with each entry formatted as:

#ID [status] subject [owner: xxx] [blocked by #x, #y]

Usage Example

ctx := context.Background()

// The Backend should be isolated at the session level
middleware, err := plantask.New(ctx, &plantask.Config{
    Backend: myBackend,
    BaseDir: "/tasks",
})
if err != nil {
    return err
}

agent, err := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model:    myModel,
    Handlers: []adk.ChatModelAgentMiddleware{middleware},
})

Typical Flow

1. Receive a complex task
       │
       ▼
2. TaskCreate to create multiple sub-tasks
   - #1: Analyze requirements
   - #2: Implement code
   - #3: Write tests
       │
       ▼
3. TaskUpdate to set dependencies
   - #2 addBlockedBy: ["1"]
   - #3 addBlockedBy: ["2"]
       │
       ▼
4. TaskList to view available tasks
       │
       ▼
5. TaskUpdate #1 → in_progress
       │
       ▼
6. After completion, TaskUpdate #1 → completed
       │
       ▼
7. Loop 4-6 until all completed
       │
       ▼
8. All completed → automatically clean up all files

Dependency Management

• blocks: “Once I complete, these tasks can start”
• blockedBy: “Once these tasks complete, I can start”

Dependency writes are bidirectional: executing addBlocks: ["2"] on Task A will simultaneously add A’s ID to Task #2’s blockedBy.

Task #1 (blocks: ["2"])  ────►  Task #2 (blockedBy: ["1"])

#2 can only start after #1 completes

Circular dependency detection is implemented via DFS reachability:

#1 blocks #2
#2 blocks #1  ← Error: would create a cyclic dependency

Implementation Details

.highwatermark

sync.Mutex

{id}.json

sonic

^\d+$

Multi-language Support

Tool descriptions support Chinese and English, switchable via the global setting:

// Use Chinese descriptions
adk.SetLanguage(adk.LanguageChinese)

// Use English descriptions (default)
adk.SetLanguage(adk.LanguageEnglish)

This setting affects all ADK built-in prompts and tool descriptions.