AI Agents in Floh Workflows

Overview

Floh can use LLMs and AI agents most safely when the model is treated as a powerful assistant inside a deterministic workflow system, not as the system of record. The model can draft, classify, summarize, extract, recommend, and gather evidence. Floh should continue to validate definitions, route graph transitions, enforce identity and authorization, execute connector side effects, pause for human decisions, and preserve audit evidence.

The product posture is:

• AI drafts; Floh validates.
• AI recommends; workflows decide.
• AI acts only inside typed, audited, policy-bound surfaces.
• Humans approve high-impact outcomes.
• Every AI contribution is explainable after the fact.

This keeps the value of LLMs while protecting the predictable execution model that workflow customers rely on.

Existing Floh Foundations

Floh already has useful boundaries for AI-assisted workflows:

• Workflow definitions are declarative graphs. The engine executes explicit steps and transitions rather than arbitrary model plans.
• Publishing is validation-gated. Draft workflows can be generated or edited by AI, but strict validation remains authoritative before production use.
• Runs pause at human gates. Approval, consent, user prompt, document submission, verification, and invitation steps can interrupt automation when judgment or confirmation is required.
• Connectors isolate outside-world side effects. External APIs belong behind connector configuration, secrets, diagnostics, retries, and error routing.
• Transforms are deterministic computation. The QuickJS sandbox is useful for shaping data but intentionally has no network or file access.
• MCP exposes a control plane for AI assistants. Agents can discover, create, validate, publish, diagnose, and document workflows through typed, scoped, audited tools.
• Audit and run diagnosis support the Prove pillar. AI-generated recommendations and actions should become first-class evidence, not invisible background behavior.

Recommended Risk Posture

Use a staged autonomy model rather than one global answer to "can the agent act?"

Stage 1: Strict Predictability

AI produces drafts, explanations, summaries, test scenarios, and recommendations. Floh validation, workflow graph logic, route guards, connector execution, and human approvals decide what actually happens.

Use this stage for:

• Workflow authoring and documentation.
• Run diagnosis.
• Approver summaries.
• Policy explanation.
• Draft notifications or ticket comments.

This should be the default for any feature that affects identity, access, audit, compliance, external side effects, money, legal obligations, or customer notifications.

Stage 2: Bounded Autonomy

AI may produce structured results that influence workflow routing, but only inside a declared schema and policy envelope. The workflow author defines the input variables, allowed model/provider, output schema, confidence handling, error routing, and human-review thresholds.

Use this stage for:

• Classification.
• Field extraction.
• Risk scoring.
• Evidence gathering.
• Choosing among low-risk, pre-approved next actions.

The model output is data. Floh still owns control flow.

Stage 3: Policy-Bound Action

Agents may execute limited actions only after the action surface is explicitly declared and auditable. This is appropriate after the first two stages prove the schema, audit, governance, and UX patterns.

Use this stage for:

• Opening a helpdesk ticket with a generated summary.
• Querying several systems to prepare an approval packet.
• Running a remediation sub-workflow that still requires approval before provisioning, revocation, or account mutation.

Avoid broad autonomous orchestration as an early product promise. It is harder to explain, test, audit, and support than bounded workflow-native behavior.

Use-Case Taxonomy

1. Design-Time AI

LLMs help administrators create and improve workflows before any production run starts.

Good use cases:

• Generate a draft workflow from a natural-language SOP.
• Convert an onboarding, access request, or offboarding policy into steps.
• Suggest missing approval branches, error transitions, catalog metadata, and group restrictions.
• Explain a workflow graph in business language.
• Generate sample catalog submissions and validation scenarios.
• Compare a draft workflow against a policy document and identify gaps.

Why it is safe:

• The output is a draft artifact.
• Existing validate_workflow and publish gates remain authoritative.
• The administrator can review the graph, variables, connector configuration, and catalog exposure before activation.

Product value:

• Shortens workflow authoring time.
• Makes complex workflow graphs easier to understand.
• Improves consistency across teams without weakening governance.

2. Run-Time Advisory AI

LLMs run inside workflows to prepare information for deterministic steps or human decision-makers.

Good use cases:

• Summarize a request for an approver.
• Extract structured fields from an uploaded document.
• Classify a support request, access request, or exception request.
• Draft a notification or ticket comment for review.
• Suggest the likely cause of a connector failure.
• Produce a concise evidence packet before an approval step.

Safety pattern:

• The model returns strict JSON, not free-form control flow.
• Output is validated before promotion into run variables.
• The workflow branches only on explicit fields such as classification, confidenceBand, requiresHumanReview, or extractionStatus.
• Low-confidence, ambiguous, or policy-sensitive output routes to approval or user_prompt.

Product value:

• Reduces repetitive reading and summarization work.
• Improves human review quality by organizing context.
• Keeps decisions visible inside normal workflow status and audit surfaces.

3. Run-Time Bounded Action AI

Agents take limited actions when the workflow author has defined the exact allowed tools and outcomes.

Good use cases:

• Choose between pre-approved connector commands based on validated evidence.
• Open a helpdesk ticket with a generated summary and structured labels.
• Query external systems for current state before an approval.
• Propose remediation after a failed run.
• Start a diagnostic sub-workflow, then pause for operator confirmation before any mutation.

Safety pattern:

• Tools are allowlisted per workflow step.
• Each tool has typed inputs, typed outputs, timeouts, and stable error codes.
• Side effects use idempotency keys tied to the workflow run and step.
• High-impact actions require an approval, consent, or user prompt before execution.

Product value:

• Lets agents do useful work without turning the workflow into an opaque chat session.
• Keeps side effects in Floh's connector, task, run, and audit model.

4. Operations AI

Agents help operators understand and recover from failed or paused runs.

Good use cases:

• Explain why a run failed or paused.
• Summarize the run timeline for support or audit.
• Suggest retry, skip, connector configuration, or workflow design fixes.
• Identify recurring failure patterns across runs.
• Generate a human-readable incident note from run and audit data.

Why it is a good early surface:

• It can start read-only.
• Existing run diagnosis APIs already provide structured context.
• Recommendations help operators without silently mutating state.

Product value:

• Speeds support and incident response.
• Makes workflow behavior more transparent.
• Strengthens the Prove pillar by turning run state into explainable evidence.

Product Approaches

Assistant-First

AI lives outside workflow runtime. It authors drafts, validates designs, diagnoses runs, writes docs, and assists operators through MCP and REST APIs.

This is the fastest and lowest-risk path because it builds on existing scoped tools, validation endpoints, and confirmation gates.

Choose this for the first product increment.

AI Connector Pattern

LLM providers are accessed through connector steps. A connector call receives structured inputs, calls the model provider, validates the response against a declared schema, and returns variables or diagnostics to the run.

This works well for summarization, extraction, classification, and drafting. It also keeps provider secrets, retries, timeouts, diagnostics, and side effects in the connector system rather than the transform sandbox.

Choose this for the first in-run advisory features.

First-Class Agent Step

Floh adds a native step type such as ai_assist or agent_task with explicit model/provider configuration, prompt template versioning, output schema, confidence gates, tool allowlists, human-review policy, and audit metadata.

This is the best long-term product shape, but it should follow real usage from the assistant-first and connector-backed MVPs. A native step is a larger contract: shared types, graph validation, designer UI, executor dispatch, run diagnosis, audit events, tests, docs, and security review all need to move together.

Guardrail Checklist

Any AI-enabled workflow feature should satisfy these controls before it can be used in production.

Accuracy and Predictability

• The AI output has a declared schema.
• The server validates the output before storing or promoting it.
• The workflow graph, not the model, controls transitions.
• Confidence is normalized into bands such as high, medium, low, and unknown.
• Low confidence and ambiguous output route to a human review step.
• The workflow author can define fallback behavior for timeout, provider error, invalid JSON, schema mismatch, and policy refusal.
• Model temperature, provider, model version, prompt template version, and schema version are recorded.

Human Review

• Access grants, access revocations, identity binding, financial outcomes, compliance outcomes, external customer communication, and destructive connector actions require human approval by default.
• Human reviewers see the model output, relevant source data, confidence, rationale, and whether the proposed action has side effects.
• Approval decisions remain ordinary Floh approval decisions; the model does not impersonate an approver.
• A workflow author can require review for specific classifications or confidence bands.

Security and Data Handling

• Prompt inputs are selected explicitly by the workflow author.
• Secret variables are never sent to a model provider unless a future explicit secret-sharing policy allows it.
• PII sent to a provider is minimized, redacted where possible, and disclosed in the step configuration.
• Raw provider payloads are not copied into audit metadata or user-visible variables by default.
• User-supplied values are bound as data, not interpolated into executable scripts.
• Provider URLs and outbound calls go through connector HTTP safety rules.
• Tool calls are allowlisted per step and scoped to the current workflow run.

Audit and Explainability

• Every AI call records provider, model, prompt template version, schema version, workflow definition version, run ID, step ID, actor, and timestamp.
• Every AI-influenced action records whether it was model-generated, deterministic, human-approved, or operator-triggered.
• Human approval records link back to the AI recommendation that was reviewed.
• Re-running a diagnosis later can explain which prompt/schema/model produced the stored recommendation.
• Prompt and schema changes follow workflow versioning semantics so in-flight runs remain explainable.

Operations

• Timeouts, rate limits, and token/cost limits are configurable.
• Provider failures have stable error codes and workflow on: "error" routes.
• Side-effecting actions have idempotency keys derived from run and step identity.
• Retry behavior is explicit and visible in the run timeline.
• Operators can disable an AI connector or provider without editing every workflow.

MVP Candidates

MVP 1: Workflow Design Copilot

Purpose: Help resource managers turn policies or SOPs into draft workflows.

Flow:

1. The user provides a policy description or SOP.
2. The assistant discovers available connectors, roles, groups, schedules, and example workflows through MCP.
3. The assistant drafts a workflow definition.
4. The assistant runs strict validation.
5. The assistant explains remaining warnings and generates test submissions.
6. A human reviews and publishes through normal Floh permissions.

Why this should come first:

• It uses existing MCP and validation surfaces.
• It avoids in-run side effects.
• It creates immediate value for workflow authoring.
• It reinforces the product message that AI accelerates design while Floh preserves control.

Success metrics:

• Time from SOP to validated draft.
• Validation warnings per generated workflow.
• Human edit distance before publish.
• Number of generated test scenarios accepted by authors.

MVP 2: AI Advisory Connector

Purpose: Let workflows call an LLM for summarization, extraction, classification, and drafting while keeping execution deterministic.

Flow:

1. A connector step sends selected variables and instructions to the configured provider.
2. The provider response must match the step's declared JSON schema.
3. Valid output is promoted into namespaced workflow variables.
4. Invalid, low-confidence, refused, or timed-out output routes to an explicit error or human review branch.
5. Approvers see the AI output as context, not as a final decision.

Good first scenarios:

• Summarize an access request before manager approval.
• Extract fields from an uploaded policy exception document.
• Classify an inbound request into standard, exception, or needs_review.

Success metrics:

• Percent of calls producing schema-valid output.
• Percent routed to human review by confidence threshold.
• Approver time saved.
• Incidents where AI output caused incorrect routing.

MVP 3: Operations Assistant

Purpose: Help operators understand failed and paused workflow runs.

Flow:

1. The assistant reads run diagnosis, step statuses, errors, and audit context.
2. It summarizes the likely cause and affected workflow area.
3. It proposes safe next actions such as retry, update connector config, edit a draft version, or escalate to an owner.
4. Mutating operations still require normal permissions and confirmation.

Why it is attractive:

• It can start read-only.
• It improves supportability.
• It provides evidence for later first-class agent behavior.

Success metrics:

• Mean time to explain failed runs.
• Operator acceptance rate of recommendations.
• Repeat failure patterns identified and fixed.

Example Workflow Patterns

Pattern 1: AI-Assisted Access Request

1. Requestor submits a catalog request.
2. AI advisory connector summarizes business justification and classifies risk.
3. A condition step routes low risk to normal manager approval and medium or high risk to security review.
4. Approvers see the summary, classification, confidence, and rationale.
5. Connector side effects happen only after approval.

Predictability boundary: the model does not approve access. It prepares context and emits typed fields that the workflow graph can inspect.

Pattern 2: Document Extraction With Review

1. User uploads a document.
2. AI advisory connector extracts declared fields into a schema.
3. A transform normalizes validated fields for downstream steps.
4. Low-confidence or missing required fields pause at a user prompt.
5. Approved fields continue to document verification or provisioning.

Predictability boundary: extracted data is not trusted until it matches schema and passes review thresholds.

Pattern 3: Failed Run Diagnosis

1. Operator opens a failed run.
2. Operations assistant reads run diagnosis and workflow documentation.
3. It identifies the failed connector, recent config changes, and suggested next action.
4. Retry, cancel, or config updates require normal permission and confirmation.

Predictability boundary: the agent explains and recommends; operators execute mutations through existing Floh actions.

Implementation Path

Phase 1: Strengthen Assistant-First Workflows

• Expand MCP prompts for workflow creation, diagnosis, and documentation.
• Make strict validation feedback more useful for AI-generated drafts.
• Add product examples that show AI-assisted workflow authoring.
• Keep publish, start-run, retry, cancel, and config-import confirmation gates.

Primary surfaces:

• packages/mcp
• POST /api/workflows/validate
• GET /api/workflows/:id/docs
• GET /api/runs/:id/diagnose
• Workflow publish/versioning APIs

Phase 2: Add AI Advisory Connector

• Define provider configuration and secret handling.
• Require explicit input selection.
• Require declared JSON schema for output.
• Validate output before returning connector variables.
• Add diagnostics for provider error, timeout, refusal, invalid JSON, and schema mismatch.
• Add example workflows for summarization, extraction, and classification.

Primary surfaces:

• Connector registry and execution model.
• Connector secrets and redaction.
• Workflow connector steps.
• Run variables and diagnostics.
• Workflow examples and integration docs.

Phase 3: Add Governance and Evaluation

• Add reusable confidence gate patterns in workflow examples or designer snippets.
• Add audit metadata for AI-generated recommendations and human-reviewed outcomes.
• Add evaluation fixtures for schema validity, routing safety, and redaction.
• Add operations reporting for AI call volume, failure rate, human-review rate, and provider cost.

Primary surfaces:

• Audit metadata.
• Run diagnosis.
• Workflow examples.
• Reports or operational dashboards.

Phase 4: Design First-Class Agent Step

• Introduce a dedicated step type only after the connector pattern proves the required product contract.
• Model the step around explicit policies: provider, prompt template, output schema, tool allowlist, confidence handling, review policy, timeout, retry, and diagnostics.
• Preserve normal graph transitions and waiting_* pause states.
• Version prompt, schema, and policy alongside workflow definitions.

Primary surfaces:

• Shared workflow types.
• Graph validation.
• Step executor.
• Designer configuration UI.
• Audit and run diagnosis.
• Tests and docs.

Non-Goals

• Do not let arbitrary model-generated plans mutate workflow state.
• Do not let LLM output bypass graph validation, permissions, approvals, or connector safety.
• Do not use transform scripts for networked LLM calls.
• Do not treat model confidence as proof.
• Do not store raw provider payloads in audit metadata by default.
• Do not promise fully autonomous workflow execution until policy, evaluation, rollback, and audit controls are proven.

Decision Summary

Floh should position AI agents as audited decision support and bounded automation. The near-term product should emphasize assistant-first authoring, run diagnosis, and advisory connector calls. First-class agent steps should be designed after those MVPs clarify the right schemas, audit fields, confidence policies, and human-review UX.