Workflows

A workflow is a multi-step business process that organizes Tasks into a directed graph. Each workflow has its own AI agent, default channels (phone, email inbox), and version history. When a member starts a workflow, they get an Assignment that tracks their progress through the tasks until they reach an outcome.

Workflows are the backbone of patient onboarding, care coordination, intake forms, appointment scheduling, support triage, and any other multi-step interaction that involves an AI agent talking to a member.

Creating a Workflow

Go to Workflows to see all workflows in your workspace.

1. Click Create Workflow
2. Fill in the form:
   • Name — e.g., "Patient Intake" or "Appointment Reminder"
   • Prompt — the instructions the AI follows when running this workflow
3. Click Create Workflow

All workflows are created as simple workflows (taskless) by default. A simple workflow runs entirely from its prompt without any task steps — the AI follows the prompt directly in a single open-ended conversation. This is enough for many use cases. If your process needs structured steps, branching, or goals, you can add tasks afterward (see Adding Tasks to a Workflow).

After creating, click the workflow in the list to open the editor, where you can configure abilities and publish a version.

Workflow UUIDs are workspace-scoped. A workflow's UUID identifies it within its workspace. The same UUID is not valid in another workspace. If you copy automation rules, webhooks, or chat-creation payloads between workspaces, recreate the workflow in the target workspace and use the new UUID. Sharing a UUID across workspaces produces "workflow not found" errors when chats or assignments try to start.

Adding Tasks to a Workflow (Optional)

Tasks are an optional enhancement for workflows that need structured steps, branching, or per-step goals. If your workflow's prompt handles the full conversation, you don't need tasks at all.

Tasks are the steps your AI walks the member through. Each task has its own prompt, goals, and abilities.

1. Open the workflow and go to the Tasks tab
2. Click Add Task
3. Fill in the form:
   • Name — keep it action-oriented ("Collect Contact Info", "Verify Insurance")
   • Prompt — the instructions the AI follows during this step
   • Goal — what completes the step (e.g., "All required fields filled")
   • Initial Message — optional first message when the AI enters this task
   • Forms — structured data the AI can fill from the conversation
4. Click Save

Connecting Tasks

Build the flow by linking tasks together:

1. Open a task and find the Sub-Tasks section, or use the visual Task Flow tab
2. Add connections from this task to other tasks
3. Optionally add a condition — e.g., branch to "Self-Pay Path" if the insurance lookup returns nothing

Tasks can run sequentially, branch on conditions, or loop back. Designate one task as the workflow's starting task (the Default Task) so new assignments know where to begin.

Workflow vs. Task Abilities

Abilities (web search, calendar booking, file access, custom toolkits) can be attached at two levels:

Use task-level abilities to keep the AI focused — for example, only enable Calendar Booking on the "Schedule Appointment" task.

Configuring Channels

Workflows can attach default channels so the AI knows how to reach members and how members can reach the workflow.

1. Open the workflow and go to the Settings tab
2. Set:
   • Default Phone Number — the number used for outbound SMS and voice calls from this workflow
   • Default Inbox — the email inbox used for inbound and outbound email on this workflow
   • Member Roles — which member roles can be assigned to this workflow
3. Click Save

Inbound calls or emails to the workflow's phone number or inbox automatically route to the agent and start (or resume) an assignment.

Publishing and Versioning

Workflows use a draft/publish model. The workflow you edit in the UI is always the draft. Members run on the active version, which is an immutable snapshot.

Publishing a Version

1. Make changes to your draft (tasks, prompts, connections, abilities)
2. In the workflow editor, click the Publish button (rocket icon) in the floating toolbar
3. Give the version a name (e.g., "launch-ready") and an optional change summary describing what changed
4. Choose whether to activate it immediately

The Publish button is disabled when the draft has no changes compared to the active version.

Activating a Version

The active version is the one new assignments use. To change it:

• Open the Versions tab, find the version you want, and click Activate
• Or, while viewing a published version, click Make Active in the floating toolbar

Existing assignments stay pinned to the version they started on, so activating a new version doesn't disrupt anyone mid-conversation.

Viewing Version History

The Versions tab shows every published version with:

• Version number and name
• Who published it and when
• A side-by-side diff between any two versions (or between a version and the current draft)

Use the version switcher (clock icon with chevron) in the floating toolbar to navigate between the draft and any published version.

Editing Version Metadata

While viewing a published version, click Edit in the floating toolbar to update the version name or change summary. The snapshot itself is immutable — only the label and notes can change.

Tracking Progress (Assignments)

When a member enters a workflow — by texting the workflow's number, replying to its inbox, or being explicitly assigned — Gravity Rail creates an Assignment. The assignment tracks which task the member is on, when they started, and the outcome.

Viewing Assignments

1. Open the workflow and go to the Assignments tab
2. Filter by:
   • Status — active, completed, abandoned
   • Member — search by name or label
   • Date range — when the assignment started or last updated
3. Click any row to open the assignment detail and see:
   • Current task
   • Conversation history
   • Forms collected
   • Files attached

A member can have at most one active assignment per workflow. Completing or abandoning the active one frees them up to start a new assignment on the same workflow.

Restarting a Workflow

If an assignment gets stuck or the member wants to start over, your AI agent can use the Workflow Restart ability mid-conversation, or an admin can mark the current assignment complete and start a new one.

Cloning Workflows

Found a workflow that almost fits a new use case? Clone it instead of starting from scratch.

1. In the workflows list, click the ⋮ menu on a workflow
2. Select Clone
3. Edit the name and slug for the new workflow
4. Click Create

The clone includes all tasks, connections, abilities, and notification rules. The original workflow is unaffected.

Common Patterns

Sequential

A linear path from intake to completion: Welcome → Collect Info → Verify → Confirm. Use this for forms, surveys, and any process with a fixed order.

Branching

The AI picks a path based on a condition. Example: after Verify Insurance, branch to In-Network Path or Self-Pay Path based on the lookup result.

Looping

A task can connect back to an earlier task. Useful for retrying a step (e.g., "Re-confirm Phone Number" loops back to Collect Info if validation fails).

Escalation

Add a Supervisor ability or a Human Handoff event rule to a task that should escalate to a human operator when the AI hits a guardrail (clinical, legal, billing complexity, etc.).

Tips

• Start simple — publish a version with just a prompt (no tasks) and run a real conversation before adding task steps or branches.
• Use task-level abilities to keep the AI focused — give Calendar Booking only to the booking task, not the whole workflow.
• Always publish and activate a version before pointing real members at the workflow. The draft never receives live conversations.
• Name versions meaningfully — "launch-ready", "post-feedback-tweaks", "added-insurance-branch" — so the version history reads like a changelog.
• Clone before experimenting — duplicate the workflow before trying a major redesign so you can fall back if needed.

Troubleshooting

"Workflow not found" when starting a chat

• Confirm the workflow UUID belongs to the same workspace as the chat. Workflow UUIDs do not cross workspaces — recreate the workflow in the target workspace and use its new UUID.
• Verify the workflow has at least one published, active version. Drafts cannot accept new chats.

"No active version" or members stuck without a response

• Open the Versions tab and confirm exactly one version is marked active.
• If you recently deactivated a version without activating another, click Activate on the version you want live.

"Default task is required"

• Open Settings and pick a starting task under Default Task, or right-click a task in the Task Flow view and choose Set as Default.

AI gets stuck on a task

• Check the task's Goal — if the goal is too strict, the AI never marks it complete. If it's too loose, the AI advances prematurely.
• Verify the task has the abilities it needs (e.g., Data Access to fill a form, Calendar Booking to book an appointment).
• Look at Sub-Tasks — if no outgoing connection matches the conversation state, the AI has nowhere to go.

Changes to the workflow aren't appearing in conversations

• Existing assignments stay pinned to the version they started on. New behavior only affects new assignments.
• If you edited the draft but didn't publish, the live version is still the older snapshot. Click Publish and activate.

Cloned workflow is missing resources

• Clones copy tasks, connections, and abilities, but app-connection credentials, phone numbers, and inboxes are workspace-scoped. Re-attach the clone's default phone number, inbox, and any external resources before publishing.

Related

• Abilities — Web search, calendar booking, file access, and other AI capabilities
• Actions — Event-triggered automations that complement workflows
• Agents — Configure the AI member that runs your workflow conversations
• Phone & Voice — Connect a phone number to a workflow for SMS and voice
• Email & Inboxes — Connect an inbox to a workflow for email-driven conversations