# How Agents Propose Workflows Using the Tinyflows Engine in OpenHuman

> Discover how agents propose workflows in OpenHuman using the Tinyflows engine. Learn how the flows_create tool validates and compiles WorkflowGraphs for structured proposals.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: how-to-guide
- Published: 2026-08-28

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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:

```rust
// 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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tools.rs).
- The **`build_builder_proposal`** function at line 779 of [`src/openhuman/flows/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/flows/tools.rs)**, while the Tinyflows engine capabilities are implemented in **[`src/openhuman/flows/tinyflows/caps/tools/native.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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.