agentic-flow-builder

What this skill does

# Agentic Flow Builder

This skill provides comprehensive guidance for building production-grade agentic flows that combine:
- **ReAcTree** hierarchical agent tree decomposition for long-horizon task planning
- **Anthropic's workflow patterns** for effective agent design
- **Business Rules Engine (BRE)** for deterministic decision-making at gates
- **Dual memory system** (episodic + working) for context management
- **SQLite persistence** with full audit trails

## Core Philosophy

**Start simple, add complexity only when justified.** Many problems can be solved with a single optimized LLM call. Only use agentic flows when the task requires:
- Multi-step decomposition
- Dynamic routing based on conditions
- Iterative refinement
- Complex orchestration across multiple specialized agents

## When to Use Agentic Flows

Create an agentic flow when you need:

1. **Long-horizon task planning** - Complex goals requiring hierarchical decomposition
2. **Deterministic gating** - Business rule-based decisions (not AI guesswork)
3. **Workflow orchestration** - Coordinating multiple specialized agents
4. **Audit requirements** - Complete traceability of decisions and outcomes
5. **Memory across executions** - Learning from past successful/failed attempts

## Architecture Components

### 0. Dynamic Agent Assignment

The system automatically selects the best agent for each task based on:
- **Task description** - Semantic matching with agent capabilities
- **Required tags** - Specific skills needed (e.g., "code", "security", "data")
- **Agent type preference** - General Claude models, Task agents, or External services
- **Performance history** - Learns from past successes/failures

**Agents are discovered dynamically:**
- Claude models (Sonnet, Opus, Haiku)
- Claude Code Task agents (auto-discovered)
- Custom plugin agents
- External API services

**Hot-reload support:** New agents are automatically available without restarting.

**Configuration example:**
```python
agent_node_config = {
    "goal": "Review code for security vulnerabilities",
    "required_tags": ["code", "security", "review"],
    "prefer_agent_type": "task",  # Prefer task agents if available
    "store_episodic": True  # Learn from this execution
}
```

The orchestrator will:
1. Find all agents with "code", "security", "review" capabilities
2. Prefer task agents (like "code-reviewer" if available)
3. Fall back to general Claude models if no specialized agent exists
4. Track performance and improve selection over time

### 1. Hierarchical Agent Tree (ReAcTree)

The flow is represented as a tree where:
- **Root nodes** - Entry points to the flow
- **Agent nodes** - LLM-capable reasoning units handling specific subgoals
- **Control flow nodes** - Orchestration using workflow patterns
- **Gate nodes** - Deterministic decision points using BRE

Each node can dynamically expand into child nodes, enabling hierarchical decomposition.

### 2. Business Rules Engine (BRE)

Provides **deterministic** decision-making at gates to avoid AI inconsistency.

**Rule condition language:**
```python
# Simple comparison
{
    "field": "user.age",
    "operator": ">=",
    "value": 18
}

# Logical AND/OR
{
    "AND": [
        {"field": "status", "operator": "==", "value": "active"},
        {"field": "balance", "operator": ">", "value": 0}
    ]
}

# Pattern matching
{
    "MATCHES": {
        "field": "email",
        "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    }
}
```

**Why BRE over AI decisions:**
- **Consistency** - Same input always produces same output
- **Explainability** - Clear audit trail of why decisions were made
- **Reliability** - No hallucination or temperature-based variance
- **Compliance** - Meets regulatory requirements for deterministic behavior

### 3. Workflow Patterns (Anthropic)

Five proven patterns for effective agent design:

#### Pattern 1: Prompt Chaining
Sequential LLM calls where each processes prior output.

**When to use:** Decomposable tasks where intermediate steps improve accuracy.

**Example:** Content generation → Translation → Fact-checking

**Implementation:**
```python
control_flow_node = {
    "node_type": "control_flow",
    "pattern": "prompt_chaining",
    "children": [
        {"name": "generate_content", "type": "agent"},
        {"name": "translate", "type": "agent"},
        {"name": "fact_check", "type": "agent"}
    ]
}
```

#### Pattern 2: Routing
Classify inputs and route to specialized handlers.

**When to use:** Multi-category problems where specialization improves performance.

**Example:** Support ticket routing (technical/billing/account)

**Implementation:** Use BRE routing rules to deterministically select the appropriate handler.

#### Pattern 3: Parallelization
Simultaneous execution via sectioning or voting.

**When to use:** Independent subtasks or when multiple perspectives improve confidence.

**Example:** Multi-file code analysis, consensus-based decision making

#### Pattern 4: Orchestrator-Workers
Central LLM dynamically breaks tasks and delegates to workers.

**When to use:** Unpredictable subtask requirements.

**Example:** Multi-file codebase modifications

#### Pattern 5: Evaluator-Optimizer
Iterative generation and evaluation loops.

**When to use:** Clear quality criteria exist and refinement improves output.

**Example:** Code generation with test-driven refinement

### 4. Dual Memory System

**Episodic Memory** - Goal-specific examples for context retrieval
- Stores successful (and failed) past executions
- Retrieved based on goal similarity
- Provides in-context learning examples

**Working Memory** - Shared observations during execution
- Stores intermediate results
- Shared across nodes in same execution
- Enables context passing without parameter threading

## Flow Creation Process

### Step 1: Define the Goal and Scope

Ask clarifying questions:
1. What is the overall goal?
2. Can this be solved with a single LLM call?
3. What are the distinct steps or decisions required?
4. Are there deterministic decision points (gates)?
5. Do you need audit trails for compliance?

**Example dialogue:**
- "What problem are you trying to solve?"
- "Walk me through the ideal workflow step by step"
- "Are there any yes/no decisions based on specific criteria?"
- "Do you need to track why certain paths were taken?"

### Step 2: Choose Execution Mode

**Workflow Mode** - Predefined paths with deterministic logic
- Predictable, testable, explainable
- Use when steps are known in advance
- Lower cost, faster execution

**Agent Mode** - LLM-directed autonomous execution
- Flexible, adapts to unexpected situations
- Use for open-ended exploration
- Higher cost, requires extensive testing

**Hybrid Mode** - Mix of both
- Workflows for known paths, agents for complex reasoning
- **Recommended** for most production use cases

### Step 3: Design the Tree Structure

Map out the hierarchical decomposition:

```
Root
├── Gate: Check Prerequisites
│   └── Agent: Validate Input Data
├── Control Flow: Main Process (Orchestrator-Workers)
│   ├── Agent: Orchestrator (Plan subtasks)
│   ├── Agent: Worker 1 (Execute subtask 1)
│   ├── Agent: Worker 2 (Execute subtask 2)
│   └── Agent: Synthesizer (Combine results)
└── Control Flow: Post-Process (Evaluator-Optimizer)
    ├── Agent: Generator (Create output)
    └── Agent: Evaluator (Validate quality)
```

### Step 4: Define Business Rules

For each gate node, define the business rules:

**Rule attributes:**
- **name** - Descriptive name
- **rule_type** - gate, validation, transformation, routing
- **condition** - Expression using BRE language
- **action** - What to do when rule fires (for routing/transformation)
- **priority** - Execution order (higher first)

**Example:**
```python
{
    "name": "Credit Approval Gate",
    "rule_type": "gate",
    "condition": {
        "AND": [
            {"field": "credit_score", "operator": ">=", "value": 650},
            {"field": "debt_to_income", "operator"