How Agents Propose Workflows Using the Tinyflows Engine in OpenHuman

Agents propose workflows by invoking the flows_create tool, which validates and compiles a WorkflowGraph through the build_builder_proposal function in src/openhuman/flows/ops.rs before returning a structured proposal payload.

OpenHuman enables AI agents to generate executable workflow proposals through the Tinyflows engine. This process transforms declarative graph definitions into validated, compilable workflows that users can review and refine before execution.

How the flows_create Tool Initiates Proposals

The entry point for workflow proposals is the flows_create tool defined in src/openhuman/flows/tools.rs. When an agent generates a workflow graph, it invokes this tool with a JSON payload containing a tinyflows::model::WorkflowGraph.

The tool forwards the graph to the core orchestration layer, specifically calling build_builder_proposal defined at line 779 in src/openhuman/flows/ops.rs. This function serves as the central dispatcher for proposal generation, coordinating validation, compilation, and readiness checks before assembling the final payload.

Validation and Compilation Pipeline

Once build_builder_proposal receives the candidate graph, it executes a multi-stage pipeline to ensure the workflow is structurally sound and executable.

Structural Validation with validate_and_migrate_graph

First, the function invokes validate_and_migrate_graph, which internally calls tinyflows::validate::validate_all. This step verifies that the graph respects Tinyflows' node-kind rules and applies any required schema migrations. If the graph contains invalid node configurations or incompatible edge connections, this stage returns an error before compilation begins.

Graph Compilation

After validation, the pipeline passes the migrated graph to tinyflows::compiler::compile. The compiler transforms the declarative WorkflowGraph into an executable representation that the Tinyflows runtime can execute. This compiled form includes resolved node dependencies and optimized execution paths.

Inference Readiness and Proposal Assembly

Before returning the proposal, the engine evaluates whether the workflow can execute in the current environment. The evaluate_inference_readiness helper checks for required LLM model availability and other runtime dependencies.

The function then assembles a workflow_proposal JSON object containing:

• type: The string "workflow_proposal" to distinguish proposals from persisted flows
• name: The user-provided workflow name
• graph: The validated and migrated WorkflowGraph
• inference_status and inference_message: Advisory fields describing any readiness issues or execution prerequisites

This payload returns to the caller and renders in the UI as an editable proposal card, allowing users to review, modify, or save the workflow.

Tinyflows Engine Integration

The Tinyflows engine resides in src/openhuman/flows/tinyflows and provides the core execution capabilities. During proposal generation, the engine leverages the ToolInvoker capability implemented in src/openhuman/flows/tinyflows/caps/tools/native.rs to handle native tool calls. This capability allows Tinyflows to interact with OpenHuman's HTTP clients, state stores, and LLM providers during both validation and eventual execution.

Code Example: Agent Workflow Proposal

The following example demonstrates how an agent constructs a proposal and how build_builder_proposal processes it internally:

// Agent invokes the flows_create tool via RPC
let tool_input = json!({
    "type": "flows_create",
    "graph": {
        "nodes": [
            { "id": "n1", "kind": "tool", "name": "http_get", "config": { "url": "https://api.example.com" } },
            { "id": "n2", "kind": "llm", "name": "gpt4", "config": {} }
        ],
        "edges": [{ "source": "n1", "target": "n2" }]
    }
});

// The core processes this through build_builder_proposal
pub(crate) async fn build_builder_proposal(
    graph: WorkflowGraph,
    name: Option<String>,
) -> Result<serde_json::Value> {
    // Validate and migrate the graph structure
    let migrated = validate_and_migrate_graph(&graph)?;
    
    // Compile to executable form
    let compiled = tinyflows::compiler::compile(&migrated)?;
    
    // Check runtime prerequisites
    let inference = evaluate_inference_readiness(&compiled).await?;
    
    // Assemble the proposal payload
    Ok(json!({
        "type": "workflow_proposal",
        "name": name.unwrap_or_default(),
        "graph": migrated,
        "inference_status": inference.status,
        "inference_message": inference.message,
    }))
}

Summary

• Agents initiate workflow proposals through the flows_create tool exposed in src/openhuman/flows/tools.rs.
• The build_builder_proposal function at line 779 of src/openhuman/flows/ops.rs orchestrates validation, compilation, and readiness checks.
• Structural validation occurs via validate_and_migrate_graph using tinyflows::validate::validate_all to ensure graph integrity.
• The Tinyflows compiler transforms valid graphs into executable representations ready for runtime execution.
• Inference readiness checks validate LLM availability and runtime prerequisites before proposal delivery.
• The final workflow_proposal payload includes the graph, name, and advisory status fields for UI rendering.

Frequently Asked Questions

How does an agent submit a workflow graph for review?

An agent submits a workflow graph by calling the flows_create tool with a JSON payload containing a WorkflowGraph definition. This tool forwards the graph to build_builder_proposal in src/openhuman/flows/ops.rs, which validates and compiles the structure before returning a proposal object that appears in the user's interface for review.

What validation does the Tinyflows engine perform on proposed workflows?

The engine performs structural validation through validate_and_migrate_graph, which invokes tinyflows::validate::validate_all to verify node-kind compliance and edge connectivity. It also runs inference readiness checks to confirm that required LLM models and runtime dependencies are available in the current environment.

Where is the workflow proposal logic implemented in the OpenHuman codebase?

The core proposal logic resides in src/openhuman/flows/ops.rs within the build_builder_proposal function starting at line 779. The tool interface is defined in src/openhuman/flows/tools.rs, while the Tinyflows engine capabilities are implemented in src/openhuman/flows/tinyflows/caps/tools/native.rs.

What distinguishes a workflow proposal from a persisted workflow?

A workflow proposal contains the field "type": "workflow_proposal" and serves as a temporary, editable preview that users must review before saving. Once approved, the same validation and compilation pipeline executes, but the system persists the result as a permanent workflow rather than returning a proposal payload.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}