lbb_workflows_manage
Create, refresh, pause, resume, run, activate, and test knowledge-graph workflows from starter templates or developer definitions, including triggers, schedules, budgets, and pre-write validation.
Instructions
Create a workflow from a starter workflow, or refresh, pause or resume a triggered workflow. Run lbb_workflows action=preview first and show the user the watch and the instance count. use creates a workflow from a starter workflow of action=starters, under a name (default: the class's local name), with its watch (class, fields) and params; the workflow then reads every instance of the class and follows each published commit. A developer workflow (starter=workflow) also takes workflow (workflow_type and version of the developer's worker), owns and batch; it needs a server with the workflow engine. use again with the same starter and name changes only what you name, and the same request again changes nothing. For starter=agent, use takes owns.properties (1 to 64), params.agent={instructions,tools?,max_iterations?,max_cost_micro_usd?,max_wall_ms?,max_read_ms?,max_proposals?,max_review_items?,pin_wait_ms?}, top-level gate and optional budget_usd_per_month; ownership, input and authority do not go inside params.agent. Tools are graph.read, files.read and propose_write; finish is implicit. Models chooses use extract, not an agent use. Hosted content-trigger creation uses PUT /v1/workflows/named with the dedicated Agent request; define here remains a developer-workflow action. A workflow that calls models (agent, ontology.fit, documents.link, documents.map, values.extract) spends model budget as it reads. refresh asks the workflow to run now and returns at once with queued; poll lbb_workflows action=get for progress. pause stops a workflow (a developer workflow, documents.parse, documents.link, documents.map or values.extract) from reading and sending, and stops the claims of a developer workflow's shards; resume lets it catch up. Without starter, pause and resume name a workflow with triggers. search.embed and ontology.fit cannot be paused. define creates or changes a workflow with triggers of the developer's worker (/v1/workflows/named): name, workflow, one trigger (class and fields for a watch, media_types for a content trigger on uploads, schedule for one run per slot of a timer, or stream for the events a client sends, in batches), owns, batch, and shards (engine identities, 1 to 16), route_by (a field that keeps work in order) and window (messages queued per shard, default 4), and optionally budget_usd_per_month (the workflow's own monthly model budget), on_exhausted (block or skip) and fan_in (the id of a fan-in identity the shards send to); it needs a server with the workflow engine, and a change of shards waits for empty inboxes. run (name, optional inputs) with inputs sends 1 to 16 explicit {iri} or {sha256} inputs as new manual-origin messages, pinned to the current revision; use the original source IRI from run_results to run a failed or pin-wait input again, not a proposed value subject. Each new message gets a new work key. Without inputs, run runs a workflow with triggers now: its watch sends every instance again, a content trigger reads its log again, a schedule sends one run outside its slots, a stream sends its partial batches. activate (name, revision) makes an earlier revision of a workflow's settings (from lbb_workflows action=revisions) the one in use: it goes through the same checks as a change, and answers the workflow with its active_revision. Show the user what changes first (compare the settings of the two revisions), and when the revision's last_tested is null say that no test is recorded for those settings and ask before you activate (activation stays allowed), and pass expected_revision, the revision you read as bound, so a change by someone else since fails with workflow_revision_conflict. A revision whose settings the graph now reads differently fails with workflow_revision_stale; then change the workflow instead. Activating changes what the workflow does from then on and deletes no data, so it is not a destructive write; a change of the watch, the parameters or the gate makes the workflow read its class again, and work that waits or runs keeps the revision it started with. tests_create tests a values.extract workflow or an Agent workflow on a server that offers hosted agent tests on chosen inputs before it writes: name (a workflow of the graph; starter defaults to values.extract) or install (a workflow not created yet, as use takes it: starter, name, watch, params, gate), and iris (at most 20) or sample (1 to 20, default 6), and models to try other models before choosing one. A test reads each input as the workflow would and calls its models (the calls count in the monthly workflow budget); it writes nothing to the graph. Poll lbb_workflows action=tests_get. tests_answer records the person's answer to one value of a read input (id, iri, property, answer: accept, reject, correct with value, or cant_tell; null removes it); it writes nothing to the graph. Answer only what the user decided. tests_cancel stops a queued or running test (id). Save a test's answers as a dataset with lbb_evals action=datasets_create.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"action": "<action>"
},
"name": "lbb_workflows_manage"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | tests_answer, tests_cancel: the test's id. | |
| iri | No | tests_answer: the input, by its instance IRI. | |
| gate | No | use: outputs below this confidence go to review instead of the graph, for a workflow with a review gate. | |
| iris | No | tests_create: the instances to test, at most 20. | |
| name | No | The triggered workflow's name, [a-z0-9][a-z0-9-]{0,62} (refresh, pause, resume: required; use: omit for the class's local name; tests_create: the workflow of the graph to test). | |
| owns | No | preview/use: agent requires properties (1 to 64) and no classes or relations; a developer workflow names what its code writes. classes it creates instances of, relations it writes as out-edges of the watched instances, properties it writes on them. Owned outputs never trigger the workflow itself. | |
| batch | No | preview/use and define, developer workflow only: instances per message, 1 to 64 (default 16); for a stream, events per message, 1 to 500 (default 100). The server checks each kind's bound. | |
| class | No | preview/use: the class whose instances the workflow watches (an IRI, or a name the ontology knows). Required unless the starter workflow's watch is fixed. | |
| graph | No | Graph to target; defaults to the connection's graph | |
| action | Yes | ||
| answer | No | tests_answer: { decision: accept | reject | correct | cant_tell, value (with correct), note }; null removes the answer. For a property without a value, accept says the text states none, and correct gives the value it states. | |
| detail | No | Response detail level. Defaults to compact. | |
| fan_in | No | define: the id of the workflow's fan-in identity (starter.<name>.<fan_in>) that the shards' turns send to, for example a catalogue. Default: none. | |
| fields | No | preview/use: the fields whose change triggers the workflow, as embedding paths (transcript, label, about/label, <https://…>). Omit for the starter workflow's own choice. | |
| inputs | No | run only: explicit original source inputs, one record IRI or uploaded-file SHA-256 per entry. New messages, new work keys; no whole-watch rescan. | |
| models | No | tests_create: other models to run the test on, per use (extract, decide), each one of the use's options in lbb_model_choice action=choices. The test's models name the ones it ran. | |
| params | No | preview/use: agent takes {agent:{instructions,tools?,max_iterations?,max_cost_micro_usd?,max_wall_ms?,max_read_ms?,max_proposals?,max_review_items?,pin_wait_ms?}}. Other settings follow the catalog entry: search.embed takes model, dim and title; ontology.fit takes context (one sentence about the text, e.g. {"context": "interviews with employees"}); workflow takes none. | |
| sample | No | tests_create: the first instances of the watched class instead, 1 to 20 (default 6). | |
| shards | No | define: engine identities that receive the messages, 1 to 16 (default 1). A change needs every shard's inbox empty. | |
| stream | No | define, in place of class: a stream of the events a client sends (POST /v1/workflows/named/events), in batches of batch events (1 to 500, default 100) or after max_wait; each event's key routes it to a shard, and shards stay as made. | |
| window | No | define: messages the watch keeps queued per shard, 1 to 128 (default 4). | |
| exclude | No | preview/use: fields to drop from the automatic choice. | |
| install | No | tests_create: a workflow not created yet, as use takes it: starter (values.extract), name, watch ({class, fields, exclude}), params and gate ({below}). | |
| starter | No | The starter workflow's catalog id from action=starters, e.g. search.embed (embeddings on a class), ontology.fit (fit from text) or workflow (a developer workflow: your worker's workflow gets the instances). get/preview/use/refresh: required. pause/resume: omit to name a workflow with triggers. | |
| trigger | No | define: the trigger's id (default watch, content, schedule or stream). queue: the trigger whose queue to read. | |
| property | No | tests_answer: the property of the value. | |
| revision | No | activate: the revision to use (wrev_ and 32 hex characters). | |
| route_by | No | define: a field of the class whose value keeps work in order: the changes of one value go to one shard. Default: the instance. | |
| schedule | No | define, in place of class: a schedule. One message per slot, at least 5 minutes apart, to one shard; a slot runs even when nothing changed (the message's changed is false). | |
| workflow | No | preview/use, developer workflow (starter=workflow) only, required there: the workflow of your worker that receives the messages. Creating it creates the instance starter.<name>. | |
| experiment | No | activate: an experiment (exp_…) whose B this activation applies; revision is B's revision. The workflow must still run the experiment's A, else experiment_outdated; when B's revision is active already, nothing changes. | |
| media_types | No | define, in place of class: a content trigger on the uploads of these media types (application/pdf, image/*, */*), one content per message, without a wait for a publication. | |
| on_exhausted | No | define: what a turn that failed for good does to its shard: block (the default) holds the inbox until a person retries or skips it; skip keeps the failed turn in the history and goes on. | |
| expected_revision | No | activate: the revision the workflow had bound when you read it; another one fails with workflow_revision_conflict. | |
| budget_usd_per_month | No | use and define: a monthly model budget in USD for this workflow, below the stack's own. For define, its turns' activity calls stop at it (429 workflow_budget_exceeded) and the turn waits until the next month. |