AI FDE Handbook

Appearance

16.4 — Project: AI Workflow Automation Platform ​

This project builds the customer-configurable HR workflow platform designed in Part 11.6 into a real, runnable system. Read Part 11.6 first.

1. Customer Scenario ​

An HR tech company (Part 11.6's scenario) needs a platform letting business customers configure multi-step approval workflows (new-hire onboarding, background checks) combining AI-driven decisions, deterministic actions, and human approvals — without custom code per customer.

2. Requirements ​

Recap of Part 11.6: customer-configurable workflow definitions compiling into an actual execution engine, long-running/resumable execution surviving days-long approval pauses, full per-workflow-instance auditability, strict per-customer execution isolation.

3. Architecture ​

Part 11.6's architecture: a customer-facing workflow-definition schema compiled into a LangGraph StateGraph at execution time, with PostgresSaver checkpointing keyed by a tenant-scoped thread_id.

4. Technology Selection ​

  • LangGraph + PostgresSaver (Part 5.1-5.3): the actual execution engine underneath the customer-facing configuration layer.
  • A constrained JSON/YAML workflow-definition schema (Part 11.6, section 13's rejection of arbitrary custom code) — customers compose from a fixed set of node types, never write raw code.
  • FastAPI for the configuration API and workflow-instance management.

5. Folder Structure ​

workflow-platform/
├── src/
│   ├── definition/
│   │   ├── schema.py               # customer-facing workflow definition schema
│   │   └── compiler.py             # compiles definition → LangGraph StateGraph (Part 5.1/5.2)
│   ├── node_types/
│   │   ├── ai_decision_node.py     # Part 3.1/3.2, configurable prompt/schema
│   │   ├── deterministic_action_node.py  # fixed API call
│   │   └── approval_node.py        # interrupt()-based, Part 5.4
│   ├── execution/
│   │   ├── engine.py               # tenant-scoped thread_id, checkpointing (Part 5.3)
│   │   └── escalation.py           # stale-pending-approval detection (Part 5.4, section 17)
│   └── api/
│       └── workflow_instances.py
├── tests/
│   ├── unit/                       # node-type behavior
│   ├── integration/                # full workflow execution, pause/resume
│   └── security/
│       └── test_bounded_execution.py  # verifies hard iteration cap regardless of customer config
├── infra/
│   └── k8s/                        # execution engine scales via PostgresSaver-backed
│                                     # statelessness (Part 5.3/7.4's exact interaction)
└── requirements.txt

6. Implementation (key excerpt) ​

The workflow compiler, turning a customer's configuration into an actual LangGraph graph — directly implementing Part 11.6's central design decision:

python
def compile_workflow_definition(definition: dict) -> StateGraph:
    """
    Compiles a customer's workflow definition into an executable LangGraph
    graph, using only the platform's fixed, well-tested node types —
    NEVER executing arbitrary customer-supplied code (Part 11.6, section 13).
    """
    graph = StateGraph(WorkflowState)
    for step in definition["steps"]:
        node_fn = NODE_TYPE_REGISTRY[step["type"]](config=step["config"])
        graph.add_node(step["name"], node_fn)

    for edge in definition["edges"]:
        graph.add_edge(edge["from"], edge["to"])

    graph.set_entry_point(definition["entry_point"])
    return graph

7. Testing ​

test_bounded_execution.py verifies that even a maliciously or accidentally misconfigured customer workflow (e.g., a cycle with no exit condition) is caught by the platform's own hard iteration cap (Part 3.7/11.6, section 8) — this test protects the platform from any single customer's configuration error, and deserves dedicated, adversarial test cases specifically probing for this.

8. Evaluation ​

Per-customer workflow completion rate and average time-to-completion (Part 8.1) as operational quality metrics; AI-decision-node accuracy evaluated per customer's specific configured criteria (Part 6.2, since different customers' "approval" criteria genuinely differ).

9. Security ​

Tenant isolation at the thread_id level (Part 5.3/9.6, structurally enforced via the checkpoint key scheme) is the central security mechanism; AI-decision-node tool access is bounded by the platform's own scoping (Part 3.3/9.2) regardless of customer configuration, preventing a customer from configuring their way into excessive-agency risk.

10. Observability ​

Full per-instance tracing (Part 6.1) as a compliance-relevant functional requirement (Part 11.6, section 9), not just operational debugging; pending-approval age monitoring (Part 5.4/8.4) given the days-long execution windows.

11. Deployment ​

Stateless execution engine instances (Part 7.4/7.5) with PostgresSaver as the sole source of truth for in-progress workflows — any instance can resume any workflow, per Part 5.3's exact durability guarantee.

12. Scaling ​

Horizontal scaling of the execution engine is straightforward given checkpoint-based statelessness (Part 5.3/7.4) — the checkpoint store's own availability becomes the binding constraint (Part 11.6, section 8's flagged critical dependency).

13. Cost Considerations ​

Per-customer, per-workflow-step cost visibility (Part 7.9/7.10) given that customers configure their own AI-decision-node usage — surfacing estimated cost per workflow configuration helps prevent customers from unknowingly configuring an expensive workflow.

14. Failure Scenarios ​

A days-long-pending approval with no response → explicit escalation/timeout policy (Part 5.4, section 8), not an indefinitely stuck instance. Checkpoint-store outage → the platform's single most critical infrastructure dependency, warranting the highest-tier availability investment (Part 11.6, section 8).

15. Improvements ​

Add a workflow-definition "dry run" simulator letting customers test a new configuration against sample data before activating it on real employee data — directly extending Part 13.2's rapid-prototyping philosophy into a customer-facing product feature.

16. Business Metrics ​

Customer-configured workflow adoption rate and average time-to-completion improvement versus each customer's prior manual process (Part 15's time-savings ROI pattern, measured per customer given the platform's inherently customer-specific workflows).

Key takeaways ​

  • The constrained, schema-based workflow definition (never arbitrary customer code) is the single design decision that makes this platform's security and auditability guarantees hold regardless of what any individual customer configures.
  • Checkpoint-store availability is this platform's most critical infrastructure dependency, given genuinely days-long execution windows — it deserves disproportionate reliability investment relative to a typical short-request system.
  • A hard, platform-enforced iteration cap (independent of customer configuration) is what protects the platform from any single customer's misconfiguration, deserving dedicated adversarial test coverage.

05-agent-platform.md