Workflow Learning Service - PRD
Author: AgentDock Team
Date: July 2025
Status: Post-Launch Enhancement
Purpose: Enhance existing procedural memory with multi-step workflow execution capabilities
Timeline: After core AgentDock platform priorities complete
Executive Summary
Unify and enhance AgentDock's existing workflow learning capabilities by creating a consolidated service that captures, learns, and executes multi-step tool sequences. The system will build upon mature procedural learning infrastructure already in production to enable deterministic replay of complex workflows and support user-submitted workflow definitions.
Problem Statement
Business Need:
- Agents repeatedly execute the same multi-step tool sequences for similar tasks
- Existing tool pattern learning lacks execution capabilities for deterministic replay
- Complex workflows (15+ steps) can be learned but not automatically executed
- No unified interface for both auto-learned and user-submitted workflow automation
Technical Challenge:
- Need unified workflow learning and execution system for multi-step tool automation
- Complex workflows (15+ steps) require deterministic replay capabilities
- User-submitted workflows need validation and execution framework
- Performance optimization required for large-scale pattern recognition
Solution Architecture
Core Concept: Enhanced Workflow Learning & Execution
Building on AgentDock's existing procedural learning foundation, the system provides complete workflow automation:
- Pattern Detection (EXISTING) - Already identifies repeated tool sequences and tracks success rates
- Workflow Storage (EXISTING) - Currently stores patterns in procedural memory with user isolation
- Smart Execution (NEW) - Add deterministic replay engine for learned workflows
- User Workflows (NEW) - Add manual workflow definition and submission capabilities
- Unified Architecture (NEW) - Consolidate existing systems into coherent service
Service Architecture
/agentdock-core/src/orchestration/workflow-learning/
├── WorkflowLearningService.ts # Core learning and execution service
├── types.ts # Workflow data structures and interfaces
├── index.ts # Service exports
└── __tests__/
└── WorkflowLearningService.test.ts
Integration Flow
// Clean separation of concerns
WorkflowLearningService // Service that learns and executes workflows
↓ stores patterns in
ProceduralMemory // Memory type that stores trigger→action patterns
↓ uses
Storage Layer // Existing storage with user isolation
Core Features
Automatic Workflow Learning
The service automatically detects and learns tool execution patterns:
- Pattern Recognition - Identifies successful tool sequences (3+ steps)
- Success Tracking - Monitors execution outcomes and performance metrics
- Confidence Scoring - Builds confidence based on repeated successful execution
- Context Awareness - Associates workflows with execution contexts
User-Submitted Workflows
Support for manually defined workflows:
- Workflow Definition - Define multi-step tool sequences via API
- Parameter Templates - Configurable parameters for flexible execution
- Validation - Ensure workflow steps are valid and executable
- Priority Handling - User workflows take precedence over auto-learned patterns
Deterministic Execution
Reliable replay of learned workflows:
- Step-by-Step Execution - Execute workflows in defined order
- Error Handling - Graceful failure recovery and partial execution
- Progress Tracking - Real-time execution progress reporting
- Performance Metrics - Track execution time and success rates
Implementation
WorkflowLearningService
// /orchestration/workflow-learning/WorkflowLearningService.ts
export class WorkflowLearningService {
constructor(
private proceduralMemory: ProceduralMemory, // Uses the actual memory type
private config: WorkflowLearningConfig
) {}
async learnToolWorkflow(data: ToolExecutionData): Promise<void> {
const { userId, agentId, toolSequence, success, context } = data;
if (toolSequence.length >= this.config.minStepsToLearn) {
const workflowPattern = this.extractWorkflowPattern(toolSequence, context);
// Store in ACTUAL procedural memory (not confusing fake memory manager)
await this.proceduralMemory.store(userId, agentId, {
trigger: workflowPattern.description,
action: JSON.stringify(workflowPattern.steps),
pattern: workflowPattern.signature,
confidence: success ? 0.8 : 0.3,
metadata: {
category: 'tool-workflow',
source: 'auto-learned',
toolSequence: workflowPattern.steps.map(s => s.toolName)
}
});
}
}
async findWorkflow(userId: string, agentId: string, context: string): Promise<ToolWorkflow | null> {
// Query ACTUAL procedural memory for tool workflows
const patterns = await this.proceduralMemory.recall(userId, agentId, context, {
metadata: { category: 'tool-workflow' },
minConfidence: 0.7
});
return this.selectBestWorkflow(patterns);
}
async submitUserWorkflow(userId: string, agentId: string, workflow: UserWorkflow): Promise<void> {
// Store user workflow in ACTUAL procedural memory
await this.proceduralMemory.store(userId, agentId, {
trigger: workflow.description,
action: JSON.stringify(workflow.steps),
pattern: `user-workflow:${workflow.name}`,
confidence: 1.0,
metadata: {
category: 'tool-workflow',
source: 'user-submitted',
workflowName: workflow.name
}
});
}
}
Integration with LLMOrchestrationService
// Clean integration in LLMOrchestrationService
export class LLMOrchestrationService {
private workflowLearningService: WorkflowLearningService;
constructor(/*...*/) {
// Initialize workflow learning service with actual procedural memory
const proceduralMemory = this.memoryManager.getProceduralMemory();
this.workflowLearningService = new WorkflowLearningService(proceduralMemory, config);
}
async handleStepFinish(event: StepFinishEvent): Promise<void> {
// Existing tool tracking logic...
// Add workflow learning
if (this.config.workflowLearning?.enabled && this.shouldLearnWorkflow(event)) {
const executionData = {
userId: this.sessionContext.userId,
agentId: this.sessionContext.agentId,
toolSequence: this.getSessionToolSequence(),
success: this.evaluateExecutionSuccess(event),
context: this.extractWorkflowContext()
};
// Learn workflow patterns (async, non-blocking)
this.workflowLearningService.learnToolWorkflow(executionData).catch(error => {
console.warn('Workflow learning failed:', error);
});
}
}
private shouldLearnWorkflow(event: StepFinishEvent): boolean {
const toolSequence = this.getSessionToolSequence();
return (
toolSequence.length >= this.config.workflowLearning.minStepsToLearn && // Default: 3
this.allToolsSuccessful(toolSequence) &&
this.isWithinLearningWindow(toolSequence) // Within 5-minute execution window
);
}
private evaluateExecutionSuccess(event: StepFinishEvent): boolean {
// All tools succeeded AND no exceptions thrown AND task completed
return event.success && !this.hasSessionErrors() && this.taskCompleted();
}
private extractWorkflowContext(): string {
// Combine session context + tool parameters for pattern matching
return `${this.sessionContext.taskDescription} | ${this.getToolParameterSummary()}`;
}
}
Data Structures (Clean Naming)
// /orchestration/workflow-learning/types.ts
interface ToolWorkflow {
id: string;
name: string;
description: string;
steps: WorkflowStep[];
triggerKeywords: string[];
source: 'auto-learned' | 'user-submitted';
confidence: number;
successCount: number;
totalExecutions: number;
createdAt: number;
lastUsed: number;
}
interface WorkflowStep {
order: number;
toolName: string;
parameters: Record<string, any>;
required: boolean;
description?: string;
}
interface UserWorkflow {
name: string;
description: string;
steps: WorkflowStep[];
triggerKeywords: string[];
}
interface ToolExecutionData {
userId: string;
agentId: string;
toolSequence: Array<{
toolName: string;
parameters: Record<string, any>;
duration: number;
success: boolean;
}>;
success: boolean;
context: string;
}
interface WorkflowLearningConfig {
enabled: boolean; // Feature flag for workflow learning
minStepsToLearn: number; // Minimum tools to form pattern (Default: 3)
minSuccessRate: number; // Minimum success rate for suggestions (Default: 0.6)
confidenceThreshold: number; // Minimum confidence for auto-suggestions (Default: 0.8)
maxWorkflowsPerAgent: number; // Storage limit per agent (Default: 1000)
learningTimeout: number; // Max learning processing time (Default: 100ms)
learningWindow: number; // Max time between tools to group as workflow (Default: 300000ms / 5min)
autoExecute: boolean; // Enable automatic workflow execution (Default: false)
suggestionMode: 'manual' | 'automatic' | 'hybrid'; // How to present suggestions (Default: 'manual')
}
Storage Strategy (Uses Existing System)
NO new storage patterns needed - uses existing procedural memory:
// Workflow patterns stored as procedural memory data
await proceduralMemory.store(userId, agentId, {
trigger: "Code review workflow",
action: JSON.stringify([
{ order: 1, toolName: "Bash", parameters: { command: "git diff main" } },
{ order: 2, toolName: "Grep", parameters: { pattern: "TODO|FIXME" } },
{ order: 3, toolName: "Bash", parameters: { command: "npm test" } }
]),
pattern: "code-review-workflow",
confidence: 0.85,
metadata: {
category: 'tool-workflow',
source: 'auto-learned',
toolSequence: ['Bash', 'Grep', 'Bash']
}
});
User isolation handled by existing procedural memory operations.
API Design (Clean)
// POST /api/workflows - User workflow submission
export async function POST(request: Request) {
const { userId, agentId, workflow } = await request.json();
// User authentication (application responsibility)
const authenticatedUserId = await extractUserFromRequest(request);
if (!authenticatedUserId || authenticatedUserId !== userId) {
return Response.json({ error: 'Unauthorized' }, { status: 401 });
}
// Use workflow learning service
const workflowLearningService = await getWorkflowLearningService();
await workflowLearningService.submitUserWorkflow(userId, agentId, workflow);
return Response.json({ success: true });
}
// GET /api/workflows - List workflows
export async function GET(request: Request) {
const { userId, agentId } = extractParams(request);
const workflowLearningService = await getWorkflowLearningService();
const workflows = await workflowLearningService.getWorkflows(userId, agentId);
return Response.json({ workflows });
}
Integration Specifications
Learning Trigger Conditions
The system learns workflows when ALL conditions are met:
- Minimum Tool Sequence: 3+ consecutive successful tool calls
- Success Criteria: All tools return success=true with no exceptions thrown
- Execution Window: Tools executed within 5-minute window (configurable)
- Task Completion: Session indicates successful task completion
- Feature Enabled:
workflowLearning.enabled = true
in configuration
Context Extraction Strategy
Workflow context combines multiple sources for pattern matching:
WorkflowContext = {
taskDescription: session.context.taskDescription,
toolParameters: extractedParameterPatterns,
executionEnvironment: session.metadata.environment,
userIntent: inferredFromToolSequence,
successIndicators: taskCompletionSignals
}
Suggestion Integration Points
Workflows are suggested at specific decision points:
- Pre-Planning: Before agent begins tool sequence planning
- Pattern Recognition: When current context matches learned patterns
- User Request: When user asks for workflow recommendations
- Error Recovery: When similar workflows succeeded in error scenarios
Production Safety Controls
- Manual Approval: All suggestions require explicit user confirmation
- Confidence Gating: Only suggest workflows above 80% confidence threshold
- Execution Isolation: Workflow execution separate from normal agent flow
- Rollback Support: Ability to interrupt and revert partial workflow execution
Implementation Phases
Phase 1: Foundation Implementation (COMPLETED)
- ✅ IMPLEMENTED: Created
/orchestration/workflow-learning/WorkflowLearningService.ts
for tool pattern learning - ✅ UNIFIED: Integrated tool pattern learning with procedural memory type storage
- ✅ CLEAN: Clear separation between memory type and workflow learning service
- ✅ STRUCTURED: Proper module organization with clean imports and exports
- ✅ READY: Foundation prepared for workflow execution engine development
Phase 2: Learning Integration (IMPLEMENTATION NEEDED)
- ✅ READY: WorkflowLearningService with pattern learning capabilities
- 🔧 IMPLEMENT: Integration with LLMOrchestrationService.handleStepFinish()
- 🔧 IMPLEMENT: Tool sequence capture and success evaluation logic
- 🔧 IMPLEMENT: Learning trigger conditions and workflow context extraction
- 🔧 IMPLEMENT: Configuration system with feature flags and thresholds
- 🔧 IMPLEMENT: Async learning pipeline with error handling
Phase 3: Execution Engine (PRIMARY DEVELOPMENT)
- 🔧 IMPLEMENT: Deterministic workflow replay with step-by-step execution
- 🔧 IMPLEMENT: User workflow submission API endpoints with validation
- 🔧 IMPLEMENT: Workflow suggestion system integrated with agent planning
- 🔧 IMPLEMENT: Partial execution recovery and error handling mechanisms
- 🔧 IMPLEMENT: Workflow performance tracking and success metrics
- 🔧 IMPLEMENT: Manual approval system for workflow suggestions
Phase 4: Production Enhancement
- EXISTING: Performance optimized using memory system capabilities
- NEW: Add execution testing beyond existing pattern learning tests
- NEW: Implement workflow execution analytics and reporting
- NEW: Deploy unified workflow learning and execution system
Success Metrics
Learning Effectiveness
- 90% accuracy in workflow pattern recognition
- 95% success rate for learned workflows
- 70% reduction in execution time for repeated tasks
- 85% of multi-step tasks automated through learned workflows
System Performance
- <5ms overhead for workflow learning during tool execution
- <100ms workflow lookup and matching using existing memory operations
- <200ms workflow execution startup time
- No impact on existing memory system performance
User Experience
- 80% of users find workflow suggestions helpful
- 60% adoption rate for suggested workflows
- 50% of agents use learned workflows within 30 days
- 95% reliability score for workflow execution
Risk Mitigation
Technical Risks
- Integration complexity: Minimized by using existing procedural memory infrastructure
- Performance impact: Controlled through async learning and efficient memory queries
- Storage bloat: Managed through existing memory decay and importance scoring
Business Risks
- False workflow triggers: High confidence thresholds prevent unwanted execution
- Workflow conflicts: Clear priority system (user-submitted > auto-learned)
- Execution failures: Graceful degradation and partial execution support
Conclusion
The Workflow Learning Service delivers intelligent automation by learning from successful tool execution patterns and enabling deterministic replay of complex workflows. By building on AgentDock's existing procedural memory infrastructure and proven user isolation patterns, the system provides:
- Automatic Learning - Captures successful multi-step tool sequences without manual intervention
- Deterministic Execution - Reliable replay of complex workflows with consistent results
- User Control - Support for manually defined workflows with priority over auto-learned patterns
- Seamless Integration - Uses existing memory system for storage with proven performance characteristics
The service transforms agents from reactive tool users into proactive workflow executors, building institutional knowledge that improves over time while maintaining the flexibility and reliability that makes AgentDock powerful.