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 through the BeforeAgent hook, giving it structured task planning capabilities:

TaskCreate

TaskGet

TaskUpdate

TaskList

Core purpose: break complex requests into trackable sub-tasks, manage dependencies between tasks, and let users see execution progress.

Architecture

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

API

Constructors

// 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 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 (filesystem package has no such type)
type DeleteRequest struct {
    FilePath string
}

💡 Note that Read returns *filesystem.FileContent (containing a Content string field), not a bare string. Import path is 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), with initial status pending.

TaskGet

Tool name constant: TaskGetToolName = "TaskGet"

taskId

Returns 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
• Adding dependencies performs cycle detection; an error is returned if a cycle would be created
• 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), each formatted as:

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

Usage Example

ctx := context.Background()

// 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 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 → automatic cleanup of all files

Dependency Management

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

Dependency writing is bidirectional: executing addBlocks: ["2"] on Task A will also write A’s ID into Task #2’s blockedBy.

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

#2 can only start after #1 completes

Cycle 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 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.