> ## Documentation Index
> Fetch the complete documentation index at: https://docs.medera.info/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Builder Canvas

> Visual workflow editor for composable behavioral-health agents.

The Agent Builder Canvas is a visual workflow editor backed by a production workflow engine. It composes **16 core node types** plus **8 BH-OS rails** into clinical workflows that ship safely from sandbox to production with WORM audit.

<CardGroup cols={4}>
  <Card title="Workflow runtime" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/play.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=f8e057788e2b694cabd1505ac4dce7b6" horizontal width="40" height="40" data-path="icons/ui/play.svg">
    · graph traversal · RLS-scoped
  </Card>

  <Card title="Execution context" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/memory.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=c830629c46ea0098a37580b8f4f65d63" horizontal width="40" height="40" data-path="icons/ui/memory.svg">
    · 5 variable scopes
  </Card>

  <Card title="Workflow queue" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/list.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=06db62b7c458fc4bcf2d5c70ee54b716" horizontal width="40" height="40" data-path="icons/ui/list.svg">
    · managed job queue · 5 workers
  </Card>

  <Card title="Node runtime" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/puzzle.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=eba447b2f1e34fad34c796c184970d9d" horizontal width="40" height="40" data-path="icons/ui/puzzle.svg">
    node runners + Block runtime
  </Card>
</CardGroup>

***

## Lifecycle

<Frame>
  <svg viewBox="0 0 720 360" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="medera/canvas-lifecycle.svg" style={{ width: '100%', height: 'auto', display: 'block', maxWidth: '780px', margin: '24px auto' }}><defs><pattern id="mdr-dots" x="0" y="0" width="10" height="10" patternUnits="userSpaceOnUse"><circle cx="1" cy="1" r="1" fill="rgba(0,0,0,0.08)" /></pattern></defs><rect x="0" y="0" width="720" height="360" fill="#ffffff" /><rect x="0" y="0" width="720" height="32" fill="#141413" /><circle cx="14" cy="16" r="3" fill="#ff5f57" /><circle cx="26" cy="16" r="3" fill="#febc2e" /><circle cx="38" cy="16" r="3" fill="#28c840" /><text x="54" y="20" fill="#9a9893" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="11" fontWeight="500">medera/canvas-lifecycle.svg</text><text x="706" y="20" textAnchor="end" fill="#9a9893" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10">canvas lifecycle</text><rect x="0" y="32" width="720" height="328" fill="#fafaf6" /><rect x="0" y="32" width="720" height="328" fill="url(#mdr-dots)" /><rect x="0.5" y="0.5" width="719" height="359" fill="none" stroke="#141413" strokeOpacity="0.18" /><text x="360.0" y="56" textAnchor="middle" fill="#141413" fontFamily="Inter, sans-serif" fontSize="15" fontWeight="600">Canvas workflow lifecycle</text><rect x="33.0" y="120.0" width="80" height="40" fill="#ffffff" stroke="rgba(0,0,0,0.08)" strokeWidth="1" /><text x="73.0" y="144" textAnchor="middle" fill="#141413" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10" fontWeight="600">Draft</text><line x1="108.0" y1="140" x2="120.0" y2="140" stroke="rgba(20,20,19,0.40)" strokeWidth="1.5" /><polygon points="120.0,136 120.0,144 126.0,140" fill="rgba(20,20,19,0.25)" /><rect x="139.0" y="120.0" width="80" height="40" fill="#ffffff" stroke="rgba(0,0,0,0.08)" strokeWidth="1" /><text x="179.0" y="144" textAnchor="middle" fill="#141413" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10" fontWeight="600">Test</text><line x1="214.0" y1="140" x2="226.0" y2="140" stroke="rgba(20,20,19,0.40)" strokeWidth="1.5" /><polygon points="226.0,136 226.0,144 232.0,140" fill="rgba(20,20,19,0.25)" /><rect x="245.0" y="120.0" width="112" height="40" fill="#76a1fc" stroke="#4f7be0" strokeWidth="1" /><text x="301.0" y="144" textAnchor="middle" fill="#ffffff" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10" fontWeight="700">Publish v1.0.0</text><line x1="352.0" y1="140" x2="364.0" y2="140" stroke="rgba(20,20,19,0.40)" strokeWidth="1.5" /><polygon points="364.0,136 364.0,144 370.0,140" fill="rgba(20,20,19,0.25)" /><rect x="383.0" y="120.0" width="142" height="40" fill="#ffffff" stroke="rgba(0,0,0,0.08)" strokeWidth="1" /><text x="454.0" y="144" textAnchor="middle" fill="#141413" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10" fontWeight="600">Auto-deploy sandbox</text><line x1="520.0" y1="140" x2="532.0" y2="140" stroke="rgba(20,20,19,0.40)" strokeWidth="1.5" /><polygon points="532.0,136 532.0,144 538.0,140" fill="rgba(20,20,19,0.25)" /><rect x="551.0" y="120.0" width="136" height="40" fill="#ffffff" stroke="rgba(0,0,0,0.08)" strokeWidth="1" /><text x="619.0" y="144" textAnchor="middle" fill="#141413" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10" fontWeight="600">Promote production</text><text x="360.0" y="220" textAnchor="middle" fill="#5c5c5a" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10">Every published version is immutable · WORM deployment log</text><text x="360.0" y="250" textAnchor="middle" fill="#5c5c5a" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10">Rollback = redeploy a previous version · full version history</text><rect x="60" y="290" width="600" height="44" fill="#dbe5ff" stroke="#76a1fc" strokeWidth="1" /><text x="360.0" y="308" textAnchor="middle" fill="#4f7be0" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="10" fontWeight="700" letterSpacing="1.6">Deployed agent URL</text><text x="360.0" y="326" textAnchor="middle" fill="#141413" fontFamily="ui-monospace, SFMono-Regular, Menlo, monospace" fontSize="11" fontWeight="600">sandbox.medera.info/{org}/{agent}-v{ver}</text></svg>
</Frame>

`agent_workflows` carries the current draft. Publishing snapshots the canvas into `agent_workflow_versions` and immediately deploys to sandbox. Promotion to production is explicit.

## Optimistic concurrency

Every draft update is guarded by `lock_version`.

Concurrent edits to the same workflow return `409 idempotency_conflict`. Draft auto-save is hash-deduped — identical payloads do not create new versions.

## Tenant isolation

The canvas is tenant-scoped end to end: - `agent_workflows.organization_id` is RLS-enforced

* Published versions inherit the org

* Deployments expose `https://sandbox.medera.info/{org}/{agent}-v{ver}` (sandbox) or `https://agents.medera.info/{org}/{agent}` (production)

* Sandbox deployments auto-expire 72 h after deploy

***

## Variable scopes

Canvas nodes can reference variables using `{{scope.path}}` syntax.

Five scopes are available:

| Scope               | Lifetime      | Mutability | Example                                  |                                                                                                                                      |
| :------------------ | :------------ | :--------- | :--------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `workflow.input`    | Per execution | Immutable  | `{{input.patient_id}}`                   |                                                                                                                                      |
| `state.<name>`      | Per execution | Mutable    | `{{state.phq9_score}}`                   |                                                                                                                                      |
| `nodes.<id>.output` | Per execution | Immutable  | `{{nodes.intake_1.output.transcript}}`   |                                                                                                                                      |
| `runtime.context`   | Per execution | Immutable  | `{{runtime.organization_id}}`            |                                                                                                                                      |
| `tenant.secret`     | Persistent    | Read-only  | `{{tenant.secret.epic_oauth_client_id}}` | `tenant.secret` is sourced from your configured secret store (SSM / Vault) — secrets are never inlined into versions or deployments. |

***

## Real-time events (real-time channel)

The executor emits the following events to the org room and per-execution room:

| Event                          | When                                                |
| :----------------------------- | :-------------------------------------------------- |
| `workflow:execution:started`   | Execution claimed by a worker                       |
| `workflow:node:executing`      | Node `_executeNode` invoked                         |
| `workflow:node:completed`      | Node returned `success`                             |
| `workflow:ehr-sync`            | An `ehr-sync` node read or wrote to a connected EHR |
| `workflow:execution:paused`    | A `user-approval` node returned `{ paused: true }`  |
| `workflow:execution:completed` | Reached `end` node                                  |
| `workflow:execution:failed`    | Node threw without an error handler                 |

***

## What's next

<CardGroup cols={2}>
  <Card title="Node Types" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/puzzle.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=eba447b2f1e34fad34c796c184970d9d" href="/agentic/canvas/node-types" width="40" height="40" data-path="icons/ui/puzzle.svg">
    16 core nodes + 8 BH-OS rails.
  </Card>

  <Card title="Variables & Scopes" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/code.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=55229463dbd5bbb579cce6192dbc5ffc" href="/agentic/canvas/variables-scopes" width="40" height="40" data-path="icons/ui/code.svg">
    Variable resolution and template syntax.
  </Card>

  <Card title="Versioning & Deployment" icon="https://mintcdn.com/medera-357fd587/iC-6rAuwl-0aQSw_/icons/ui/rocket.svg?fit=max&auto=format&n=iC-6rAuwl-0aQSw_&q=85&s=3589c7c988f4bcd5e2811bac87becdb9" href="/agentic/canvas/versioning-deployment" width="40" height="40" data-path="icons/ui/rocket.svg">
    Sandbox-first deployment with WORM audit.
  </Card>

  <Card title="Guardrails" icon="https://mintcdn.com/medera-357fd587/n1mgcc3nR2sq_PoL/icons/ui/shield-check.svg?fit=max&auto=format&n=n1mgcc3nR2sq_PoL&q=85&s=6909d120dcab3cdfef838294f042d00c" href="/agentic/canvas/guardrails" width="40" height="40" data-path="icons/ui/shield-check.svg">
    HIPAA + 42 CFR Part 2 enforcement.
  </Card>
</CardGroup>