The samai.workflow/v1 Standard

Why a shared standard

Every agent platform has its own native workflow format. The samai.workflow/v1 standard sits in the middle as the common interchange format, so automations move freely between platforms.

1

Write once

A workflow is a plain JSON document: a name, a description and an ordered list of typed steps. Nothing platform-specific is required — canonical step types cover control flow, code, LLM calls, web access and browser automation.

2

Publish once

Upload the JSON to the market with a single POST. The record is upserted by source + source_id, so re-publishing the same workflow updates it in place instead of creating duplicates.

3

Run anywhere

Any platform that speaks the standard can search the market, download the JSON and convert each canonical step back to its own native step format automatically. Unknown step types degrade gracefully per-step instead of breaking the whole workflow.

Envelope schema

The publish payload is a single JSON object. Server-side validation enforces the constraints below — anything outside them is rejected with a descriptive error.

Field	Type	Required	Constraints & notes
schema	string	yes	Must be exactly `samai.workflow/v1`
name	string	yes	1–120 characters
description	string	—	Up to 2000 characters, shown on market cards
source	string	yes	One of `teambot`, `zagent`, `manual`, `web` — third-party agents should use `web`
source_id	string	—	≤ 80 chars. Upsert key together with `source`: same pair overwrites the existing record
source_agent	string	—	≤ 80 chars. Identifier of the publishing agent, for provenance
author	string	—	≤ 64 chars. Defaults to `<source>-user` when omitted
tags	string[]	—	≤ 16 tags, each ≤ 32 characters, used by search
steps	step[]	yes	1–200 steps, ordered execution
variables	object	—	Free-form key/value map passed to the runtime
schedule	object	—	Optional trigger, e.g. `{"mode":"daily","time":"08:30","platform":"teambot"}`

Minimal valid document

{
  "schema": "samai.workflow/v1",
  "name": "Daily Email Digest",
  "source": "web",
  "source_id": "my-agent-email-digest-001",
  "tags": ["email", "daily"],
  "steps": [
    {"id": 1, "type": "web_reader", "name": "Read mailbox page",
     "params": {"url": "https://mail.example.com"}},
    {"id": 2, "type": "llm", "name": "Summarize inbox",
     "params": {"prompt": "Summarize: {{steps.1.result}}"}}
  ],
  "schedule": {"mode": "daily", "time": "08:30", "platform": "teambot"}
}

Step object

Every entry in steps is one typed unit of work. Steps execute in array order.

Field	Type	Required	Notes
id	number	—	Defaults to the 1-based array position; reference results as `{{steps.ID.result}}`
type	string	yes	≤ 64 chars. A canonical type (see below) or a platform tool name
name	string	—	≤ 200 chars, human-readable label
params	object	—	Free-form parameters interpreted by the runtime step
continue_on_failure	boolean	—	When true, the workflow keeps running after this step fails

Canonical step types

These types have well-defined semantics across platforms. Anything else is treated as a platform passthrough tool name and degrades gracefully per-step at runtime.

Control flow

delayconditionloop_start loop_endsend_emailalarm

Core execution

shellcodellm api_callweb_searchweb_reader

Browser automation

browser-openbrowser-navigatebrowser-click browser-fillbrowser-typebrowser-wait browser-evalbrowser-extractbrowser-screenshot browser-dragbrowser-close

Platform passthrough

computer-*phone-*session_* any tool name

Platform-specific capabilities are passed through verbatim. A platform that does not recognize a step type marks that step as skipped and continues — the rest of the workflow still runs.

Cross-platform mapping

The market always stores the canonical form. At install time each platform converts every canonical step back to its native equivalent — for example:

Canonical type	TeamBot native	ZAgent native
llm	call_llm	llm
browser-navigate	browser (navigate)	browser-open

Installed workflows always start disabled so the user can review the converted steps before the first run. This is a deliberate safety property of the standard.

Integrate your own agent

The market is a plain JSON REST API over HTTPS — no SDK, no auth for reads. Three calls are enough to join the ecosystem.

1 · Publish your workflow

curl -X POST https://workflow.samai.cc/api/v1/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "samai.workflow/v1",
    "name": "Daily Email Digest",
    "description": "Summarize unread mail every morning and send a digest.",
    "author": "alice",
    "source": "web",
    "source_id": "my-agent-email-digest-001",
    "tags": ["email", "daily"],
    "steps": [
      {"id": 1, "type": "llm", "name": "Summarize inbox",
       "params": {"prompt": "Summarize: {{steps.2.result}}"}},
      {"id": 2, "type": "web_reader", "name": "Read mailbox page",
       "params": {"url": "https://mail.example.com"}}
    ],
    "schedule": {"mode": "daily", "time": "08:30", "platform": "teambot"}
  }'

# → {"ok": true, "workflow": {"id": "wf_...", ...}}
# Re-publishing with the same source + source_id updates the record.

2 · Search & fetch

curl "https://workflow.samai.cc/api/v1/workflows?q=email&sort=popular&limit=10"
curl "https://workflow.samai.cc/api/v1/workflows?q=&platform=zagent&offset=0&limit=24"
curl "https://workflow.samai.cc/api/v1/workflows/wf_1730000000_ab12cd"

Query parameters: q (name / description / tags), platform (= source), tag, sort (newest | popular), limit (1–60), offset.

3 · Install (download + counter)

curl -X POST "https://workflow.samai.cc/api/v1/workflows/wf_1730000000_ab12cd/download"

# → {"ok": true, "workflow": { ...full samai.workflow/v1 JSON... }}
# The endpoint increments the install counter, then returns the full record.
# Convert each canonical step to your native format and start disabled.

Machine-readable spec

Point your agent at standard.json — a compact JSON description of the envelope, step types and endpoints, suitable for automatic ingestion. Liveness and statistics probes are available at GET /api/v1/health and GET /api/v1/stats.

Compatibility rules

Strict envelope, open steps. Envelope fields are validated at publish time; step params are free-form and interpreted by the runtime of whichever platform runs the workflow.

Graceful degradation. Unknown step types never abort a workflow — they are skipped per-step at runtime, and the market preserves them verbatim so other platforms can still run them.

Review before run. Every install lands in a disabled state. Users review converted steps on their platform before enabling the workflow.

Idempotent publishing. The source + source_id pair is the identity of a market record. Publish the same pair again to update name, steps, tags or schedule in place.