Core Concepts

Six concepts cover everything you need to build with Hyphen.

1. Workflows

A workflow is a JSON spec that defines a process. It has a name, an optional top-level condition gate, and an ordered array of actions (steps).

{
  "name": "invoice_reconciliation",
  "definition": {
    "condition": { "greaterThan": ["@input.invoices.length", 0] },
    "actions": [
      { "type": "matcher", "properties": { ... } },
      { "type": "loop", "properties": { "mode": "react", ... } },
      { "type": "PbotApproval", "properties": { ... } }
    ]
  }
}

Workflows are created via POST /workflows, executed via POST /workflows/:id/execute, and produce runs with full audit trails. They can also be generated from plain language via POST /ai/generate-workflow.

2. Actions

Actions are reusable operations you register once and reference by name in any workflow. Five kinds:

Register an action:

curl -X POST http://localhost:3009/actions \
  -H "X-Org-Id: your-org" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "fetch_customer",
    "kind": "http",
    "url": "https://api.example.com/customers/{{customer_id}}",
    "http_method": "GET",
    "passthrough": true
  }'

Use it in a workflow step:

{ "type": "fetch_customer", "properties": { "customer_id": "@input.id" } }

Use it as a ReAct agent tool:

{ "tools": [{ "type": "action", "name": "fetch_customer" }] }

All action kinds work everywhere — in workflow steps, foreach loops, and as agent tools.

→ Full reference: Actions

3. Primitives

Primitives are built-in workflow steps that don't require registration. They handle core orchestration patterns:

Primitives use the step type field directly — no registration required:

{ "type": "matcher", "properties": { "left": "@input.invoices", "right": "@input.payments", ... } }
{ "type": "PbotApproval", "properties": { "comment": "Review this transaction" } }

4. Context

Context is how data flows between steps. Every workflow run maintains a context object that grows as steps execute.

@path References

The @ prefix references values from context:

Template Interpolation

Use {{ }} for string interpolation inside property values:

{ "message": "Hello {{input.customer_name}}, your balance is ${{context.balance}}" }

Data Flow Example

→ Full reference: Context Resolution

5. Agents

Agents are ReAct (Reasoning + Acting) loops — AI that thinks, uses tools, observes results, and iterates toward an objective. They operate within boundaries defined by the workflow spec.

{
  "type": "loop",
  "properties": {
    "mode": "react",
    "objective": "Investigate this unmatched invoice and recommend an action",
    "tools": [
      { "type": "action", "name": "lookup_erp_invoice" },
      { "type": "action", "name": "gmail_send" }
    ],
    "max_iterations": 10,
    "on_stuck": { "iterations": 3, "action": "escalate" },
    "result_key": "investigation"
  }
}

Governance Model

Every agent runs inside a cage defined by its spec:

Structural permissioning — only tools explicitly declared in tools are available. The agent cannot discover or invent capabilities.

Bounded iteration — max_iterations caps prevent runaway execution.

Stuck detection — on_stuck identifies when an agent loops without progress and triggers recovery (fail, retry with hint, or escalate to human).

Human escalation — __pause_for_human__ lets the agent request human input when confidence is low. The human's decision becomes part of the reasoning trace.

Reasoning traces — every iteration captures thought, action, parameters, and observation. Full chain of reasoning, queryable and auditable.

Tool Declaration

Tools support two formats — string shorthand for simple references, and full object definitions for explicit parameter schemas:

{
  "tools": [
    { "type": "action", "name": "lookup_ticket" },
    { "type": "action", "name": "verify_identity" },
    { "type": "workflow", "id": "wf_escalation_review" }
  ]
}

Action tools reference registered actions by name — the resolver automatically fetches descriptions and parameters. Workflow tools reference workflows by ID, letting the agent trigger sub-workflows. Built-in tools (__complete__, __pause_for_human__, __store_memory__, __retrieve_memory__, __log_progress__) are always auto-injected.

Three Deployment Patterns

→ Full reference: Agents

6. Runs

A run is a single execution of a workflow. It captures everything: input, step outputs, agent reasoning traces, human decisions, timing, and final status.

# Execute a workflow → get a run
curl -X POST http://localhost:3009/workflows/{id}/execute \
  -H "X-Org-Id: your-org" \
  -d '{ "invoices": [...], "payments": [...] }'
# → { "id": "run_abc123", "status": "running" }

# Check status
curl http://localhost:3009/runs/run_abc123/status \
  -H "X-Org-Id: your-org"

Run Statuses

What's Captured

Every run persists: the full input payload, each step's output, all agent reasoning traces (thought → action → observation for every iteration), human approval decisions with reviewer identity and comments, and timestamps for every state transition. This is the audit trail — queryable, exportable, and persistent.

→ API reference: Run Status

How They Fit Together

A typical production deployment:

1. Register actions — connect your ERP, CRM, databases, and communication tools
2. Define a workflow — compose primitives and actions with conditional logic
3. Execute — send data in, get a run back
4. Monitor — poll status, handle approvals, read reasoning traces
5. Audit — every decision has a paper trail